diff --git a/config/rag.json b/config/rag.json new file mode 100644 index 000000000..a1a99eb82 --- /dev/null +++ b/config/rag.json @@ -0,0 +1,4 @@ +{ + "ragFolder": "RAG", + "chunkSize": 500 +} diff --git a/node_modules/.package-lock.json b/node_modules/.package-lock.json index 930cac8bb..f5fab9630 100644 --- a/node_modules/.package-lock.json +++ b/node_modules/.package-lock.json @@ -139,6 +139,30 @@ "node": ">=18" } }, + "node_modules/@cspotcode/source-map-support": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", + "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.9" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@cspotcode/source-map-support/node_modules/@jridgewell/trace-mapping": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", + "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.0.3", + "@jridgewell/sourcemap-codec": "^1.4.10" + } + }, "node_modules/@csstools/color-helpers": { "version": "5.0.2", "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-5.0.2.tgz", @@ -2261,6 +2285,34 @@ "@testing-library/dom": ">=7.21.4" } }, + "node_modules/@tsconfig/node10": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.11.tgz", + "integrity": "sha512-DcRjDCujK/kCk/cUe8Xz8ZSpm8mS3mNNpta+jGCA6USEDfktlNvm1+IuZ9eTcDbNk41BHwpHHeW+N1lKCz4zOw==", + "devOptional": true, + "license": "MIT" + }, + "node_modules/@tsconfig/node12": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/@tsconfig/node12/-/node12-1.0.11.tgz", + "integrity": "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==", + "devOptional": true, + "license": "MIT" + }, + "node_modules/@tsconfig/node14": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@tsconfig/node14/-/node14-1.0.3.tgz", + "integrity": "sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==", + "devOptional": true, + "license": "MIT" + }, + "node_modules/@tsconfig/node16": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@tsconfig/node16/-/node16-1.0.4.tgz", + "integrity": "sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==", + "devOptional": true, + "license": "MIT" + }, "node_modules/@types/aria-query": { "version": "5.0.4", "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz", @@ -2364,13 +2416,25 @@ "license": "MIT" }, "node_modules/@types/node": { - "version": "22.7.9", - "resolved": "https://registry.npmjs.org/@types/node/-/node-22.7.9.tgz", - "integrity": "sha512-jrTfRC7FM6nChvU7X2KqcrgquofrWLFDeYC1hKfwNWomVvrn7JIksqf344WN2X/y8xrgqBd2dJATZV4GbatBfg==", + "version": "22.17.2", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.17.2.tgz", + "integrity": "sha512-gL6z5N9Jm9mhY+U2KXZpteb+09zyffliRkZyZOHODGATyC5B1Jt/7TzuuiLkFsSUMLbS1OLmlj/E+/3KF4Q/4w==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/@types/pg": { + "version": "8.15.5", + "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.15.5.tgz", + "integrity": "sha512-LF7lF6zWEKxuT3/OR8wAZGzkg4ENGXFNyiV/JeOt9z5B+0ZVwbql9McqX5c/WStFq1GaGso7H1AzP/qSzmlCKQ==", "dev": true, "license": "MIT", "dependencies": { - "undici-types": "~6.19.2" + "@types/node": "*", + "pg-protocol": "*", + "pg-types": "^2.2.0" } }, "node_modules/@types/prop-types": { @@ -2791,7 +2855,7 @@ "version": "8.13.0", "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.13.0.tgz", "integrity": "sha512-8zSiw54Oxrdym50NlZ9sUusyO1Z1ZchgRLWRaK6c86XJFClyCgFKetdowBg5bKxyp/u+CDBJG4Mpp0m3HLZl9w==", - "dev": true, + "devOptional": true, "license": "MIT", "bin": { "acorn": "bin/acorn" @@ -2810,6 +2874,19 @@ "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, + "node_modules/acorn-walk": { + "version": "8.3.4", + "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.4.tgz", + "integrity": "sha512-ueEepnujpqee2o5aIYnvHU6C0A42MNdsIDeqy5BydrkuC5R1ZuUFnm27EeFJGoEHJQgn3uleRvmTXaJgfXbt4g==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "acorn": "^8.11.0" + }, + "engines": { + "node": ">=0.4.0" + } + }, "node_modules/agent-base": { "version": "7.1.4", "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz", @@ -3621,6 +3698,13 @@ "dev": true, "license": "MIT" }, + "node_modules/create-require": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz", + "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==", + "devOptional": true, + "license": "MIT" + }, "node_modules/cross-spawn": { "version": "7.0.6", "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", @@ -3888,6 +3972,16 @@ "integrity": "sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==", "license": "Apache-2.0" }, + "node_modules/diff": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.2.tgz", + "integrity": "sha512-58lmxKSA4BNyLz+HHMUzlOEpg09FV+ev6ZMe3vJihgdxzgcwZ8VoEEPmALCZG9LmqfVoNMMKpttIYTVG6uDY7A==", + "devOptional": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, "node_modules/dlv": { "version": "1.1.3", "resolved": "https://registry.npmjs.org/dlv/-/dlv-1.1.3.tgz", @@ -3912,6 +4006,18 @@ "csstype": "^3.0.2" } }, + "node_modules/dotenv": { + "version": "17.2.1", + "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-17.2.1.tgz", + "integrity": "sha512-kQhDYKZecqnM0fCnzI5eIv5L4cAe/iRI+HqMbO/hbRdTAeXDG+M9FjipUxNfbARuEg4iHIbhnhs78BCHNbSxEQ==", + "license": "BSD-2-Clause", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://dotenvx.com" + } + }, "node_modules/eastasianwidth": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz", @@ -5156,6 +5262,13 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/make-error": { + "version": "1.3.6", + "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz", + "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==", + "devOptional": true, + "license": "ISC" + }, "node_modules/merge2": { "version": "1.4.1", "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", @@ -5464,6 +5577,95 @@ "node": ">= 14.16" } }, + "node_modules/pg": { + "version": "8.16.3", + "resolved": "https://registry.npmjs.org/pg/-/pg-8.16.3.tgz", + "integrity": "sha512-enxc1h0jA/aq5oSDMvqyW3q89ra6XIIDZgCX9vkMrnz5DFTw/Ny3Li2lFQ+pt3L6MCgm/5o2o8HW9hiJji+xvw==", + "license": "MIT", + "dependencies": { + "pg-connection-string": "^2.9.1", + "pg-pool": "^3.10.1", + "pg-protocol": "^1.10.3", + "pg-types": "2.2.0", + "pgpass": "1.0.5" + }, + "engines": { + "node": ">= 16.0.0" + }, + "optionalDependencies": { + "pg-cloudflare": "^1.2.7" + }, + "peerDependencies": { + "pg-native": ">=3.0.1" + }, + "peerDependenciesMeta": { + "pg-native": { + "optional": true + } + } + }, + "node_modules/pg-cloudflare": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/pg-cloudflare/-/pg-cloudflare-1.2.7.tgz", + "integrity": "sha512-YgCtzMH0ptvZJslLM1ffsY4EuGaU0cx4XSdXLRFae8bPP4dS5xL1tNB3k2o/N64cHJpwU7dxKli/nZ2lUa5fLg==", + "license": "MIT", + "optional": true + }, + "node_modules/pg-connection-string": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.9.1.tgz", + "integrity": "sha512-nkc6NpDcvPVpZXxrreI/FOtX3XemeLl8E0qFr6F2Lrm/I8WOnaWNhIPK2Z7OHpw7gh5XJThi6j6ppgNoaT1w4w==", + "license": "MIT" + }, + "node_modules/pg-int8": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz", + "integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==", + "license": "ISC", + "engines": { + "node": ">=4.0.0" + } + }, + "node_modules/pg-pool": { + "version": "3.10.1", + "resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.10.1.tgz", + "integrity": "sha512-Tu8jMlcX+9d8+QVzKIvM/uJtp07PKr82IUOYEphaWcoBhIYkoHpLXN3qO59nAI11ripznDsEzEv8nUxBVWajGg==", + "license": "MIT", + "peerDependencies": { + "pg": ">=8.0" + } + }, + "node_modules/pg-protocol": { + "version": "1.10.3", + "resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.10.3.tgz", + "integrity": "sha512-6DIBgBQaTKDJyxnXaLiLR8wBpQQcGWuAESkRBX/t6OwA8YsqP+iVSiond2EDy6Y/dsGk8rh/jtax3js5NeV7JQ==", + "license": "MIT" + }, + "node_modules/pg-types": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz", + "integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==", + "license": "MIT", + "dependencies": { + "pg-int8": "1.0.1", + "postgres-array": "~2.0.0", + "postgres-bytea": "~1.0.0", + "postgres-date": "~1.0.4", + "postgres-interval": "^1.1.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/pgpass": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.5.tgz", + "integrity": "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==", + "license": "MIT", + "dependencies": { + "split2": "^4.1.0" + } + }, "node_modules/picocolors": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", @@ -5643,6 +5845,45 @@ "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==", "license": "MIT" }, + "node_modules/postgres-array": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz", + "integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/postgres-bytea": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.0.tgz", + "integrity": "sha512-xy3pmLuQqRBZBXDULy7KbaitYqLcmxigw14Q5sj8QBVLqEwXfeybIKVWiqAXTlcvdvb0+xkOtDbfQMOf4lST1w==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/postgres-date": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz", + "integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/postgres-interval": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz", + "integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==", + "license": "MIT", + "dependencies": { + "xtend": "^4.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/prelude-ls": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz", @@ -6245,6 +6486,15 @@ "node": ">=0.10.0" } }, + "node_modules/split2": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz", + "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==", + "license": "ISC", + "engines": { + "node": ">= 10.x" + } + }, "node_modules/stackback": { "version": "0.0.2", "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz", @@ -6762,6 +7012,57 @@ "integrity": "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==", "license": "Apache-2.0" }, + "node_modules/ts-node": { + "version": "10.9.2", + "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz", + "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@cspotcode/source-map-support": "^0.8.0", + "@tsconfig/node10": "^1.0.7", + "@tsconfig/node12": "^1.0.7", + "@tsconfig/node14": "^1.0.0", + "@tsconfig/node16": "^1.0.2", + "acorn": "^8.4.1", + "acorn-walk": "^8.1.1", + "arg": "^4.1.0", + "create-require": "^1.1.0", + "diff": "^4.0.1", + "make-error": "^1.1.1", + "v8-compile-cache-lib": "^3.0.1", + "yn": "3.1.1" + }, + "bin": { + "ts-node": "dist/bin.js", + "ts-node-cwd": "dist/bin-cwd.js", + "ts-node-esm": "dist/bin-esm.js", + "ts-node-script": "dist/bin-script.js", + "ts-node-transpile-only": "dist/bin-transpile.js", + "ts-script": "dist/bin-script-deprecated.js" + }, + "peerDependencies": { + "@swc/core": ">=1.2.50", + "@swc/wasm": ">=1.2.50", + "@types/node": "*", + "typescript": ">=2.7" + }, + "peerDependenciesMeta": { + "@swc/core": { + "optional": true + }, + "@swc/wasm": { + "optional": true + } + } + }, + "node_modules/ts-node/node_modules/arg": { + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz", + "integrity": "sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==", + "devOptional": true, + "license": "MIT" + }, "node_modules/tslib": { "version": "2.8.0", "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.0.tgz", @@ -6782,10 +7083,10 @@ } }, "node_modules/typescript": { - "version": "5.6.3", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.6.3.tgz", - "integrity": "sha512-hjcS1mhfuyi4WW8IWtjP7brDrG2cuDZukyrYrSauoXGNgx0S7zceP07adYkJycEr56BOUTNPzbInooiN3fn1qw==", - "dev": true, + "version": "5.9.2", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.2.tgz", + "integrity": "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A==", + "devOptional": true, "license": "Apache-2.0", "bin": { "tsc": "bin/tsc", @@ -6820,10 +7121,10 @@ } }, "node_modules/undici-types": { - "version": "6.19.8", - "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.19.8.tgz", - "integrity": "sha512-ve2KP6f/JnbPBFyobGHuerC9g1FYGn/F8n1LWTwNxCEzd6IfqTwUQcNXgEtmmQ6DlRrC1hrSrBnCZPokRrDHjw==", - "dev": true, + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "devOptional": true, "license": "MIT" }, "node_modules/update-browserslist-db": { @@ -6916,6 +7217,13 @@ "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", "license": "MIT" }, + "node_modules/v8-compile-cache-lib": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz", + "integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==", + "devOptional": true, + "license": "MIT" + }, "node_modules/vaul": { "version": "0.9.9", "resolved": "https://registry.npmjs.org/vaul/-/vaul-0.9.9.tgz", @@ -7376,6 +7684,15 @@ "dev": true, "license": "MIT" }, + "node_modules/xtend": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz", + "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==", + "license": "MIT", + "engines": { + "node": ">=0.4" + } + }, "node_modules/yaml": { "version": "2.6.0", "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.6.0.tgz", @@ -7388,6 +7705,16 @@ "node": ">= 14" } }, + "node_modules/yn": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz", + "integrity": "sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==", + "devOptional": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, "node_modules/yocto-queue": { "version": "0.1.0", "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", diff --git a/node_modules/@types/node/README.md b/node_modules/@types/node/README.md index 7916ce66b..bccf99963 100644 --- a/node_modules/@types/node/README.md +++ b/node_modules/@types/node/README.md @@ -5,11 +5,11 @@ This package contains type definitions for node (https://nodejs.org/). # Details -Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node. +Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node/v22. ### Additional Details - * Last updated: Wed, 23 Oct 2024 03:36:41 GMT + * Last updated: Fri, 15 Aug 2025 08:39:32 GMT * Dependencies: [undici-types](https://npmjs.com/package/undici-types) # Credits -These definitions were written by [Microsoft TypeScript](https://github.com/Microsoft), [Alberto Schiabel](https://github.com/jkomyno), [Alvis HT Tang](https://github.com/alvis), [Andrew Makarov](https://github.com/r3nya), [Benjamin Toueg](https://github.com/btoueg), [Chigozirim C.](https://github.com/smac89), [David Junger](https://github.com/touffy), [Deividas Bakanas](https://github.com/DeividasBakanas), [Eugene Y. Q. Shen](https://github.com/eyqs), [Hannes Magnusson](https://github.com/Hannes-Magnusson-CK), [Huw](https://github.com/hoo29), [Kelvin Jin](https://github.com/kjin), [Klaus Meinhardt](https://github.com/ajafff), [Lishude](https://github.com/islishude), [Mariusz Wiktorczyk](https://github.com/mwiktorczyk), [Mohsen Azimi](https://github.com/mohsen1), [Nikita Galkin](https://github.com/galkin), [Parambir Singh](https://github.com/parambirs), [Sebastian Silbermann](https://github.com/eps1lon), [Thomas den Hollander](https://github.com/ThomasdenH), [Wilco Bakker](https://github.com/WilcoBakker), [wwwy3y3](https://github.com/wwwy3y3), [Samuel Ainsworth](https://github.com/samuela), [Kyle Uehlein](https://github.com/kuehlein), [Thanik Bhongbhibhat](https://github.com/bhongy), [Marcin Kopacz](https://github.com/chyzwar), [Trivikram Kamat](https://github.com/trivikr), [Junxiao Shi](https://github.com/yoursunny), [Ilia Baryshnikov](https://github.com/qwelias), [ExE Boss](https://github.com/ExE-Boss), [Piotr Błażejewicz](https://github.com/peterblazejewicz), [Anna Henningsen](https://github.com/addaleax), [Victor Perin](https://github.com/victorperin), [Yongsheng Zhang](https://github.com/ZYSzys), [NodeJS Contributors](https://github.com/NodeJS), [Linus Unnebäck](https://github.com/LinusU), [wafuwafu13](https://github.com/wafuwafu13), [Matteo Collina](https://github.com/mcollina), and [Dmitry Semigradsky](https://github.com/Semigradsky). +These definitions were written by [Microsoft TypeScript](https://github.com/Microsoft), [Alberto Schiabel](https://github.com/jkomyno), [Andrew Makarov](https://github.com/r3nya), [Benjamin Toueg](https://github.com/btoueg), [David Junger](https://github.com/touffy), [Mohsen Azimi](https://github.com/mohsen1), [Nikita Galkin](https://github.com/galkin), [Sebastian Silbermann](https://github.com/eps1lon), [Wilco Bakker](https://github.com/WilcoBakker), [Marcin Kopacz](https://github.com/chyzwar), [Trivikram Kamat](https://github.com/trivikr), [Junxiao Shi](https://github.com/yoursunny), [Ilia Baryshnikov](https://github.com/qwelias), [ExE Boss](https://github.com/ExE-Boss), [Piotr Błażejewicz](https://github.com/peterblazejewicz), [Anna Henningsen](https://github.com/addaleax), [Victor Perin](https://github.com/victorperin), [NodeJS Contributors](https://github.com/NodeJS), [Linus Unnebäck](https://github.com/LinusU), [wafuwafu13](https://github.com/wafuwafu13), [Matteo Collina](https://github.com/mcollina), [Dmitry Semigradsky](https://github.com/Semigradsky), and [René](https://github.com/Renegade334). diff --git a/node_modules/@types/node/assert.d.ts b/node_modules/@types/node/assert.d.ts index d7e371918..c340ef667 100644 --- a/node_modules/@types/node/assert.d.ts +++ b/node_modules/@types/node/assert.d.ts @@ -956,6 +956,18 @@ declare module "assert" { * @since v13.6.0, v12.16.0 */ function doesNotMatch(value: string, regExp: RegExp, message?: string | Error): void; + /** + * Tests for partial deep equality between the `actual` and `expected` parameters. + * "Deep" equality means that the enumerable "own" properties of child objects + * are recursively evaluated also by the following rules. "Partial" equality means + * that only properties that exist on the `expected` parameter are going to be + * compared. + * + * This method always passes the same test cases as `assert.deepStrictEqual()`, + * behaving as a super set of it. + * @since v22.13.0 + */ + function partialDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void; /** * In strict assertion mode, non-strict methods behave like their corresponding strict methods. For example, * {@link deepEqual} will behave like {@link deepStrictEqual}. @@ -1015,6 +1027,7 @@ declare module "assert" { | "deepStrictEqual" | "ifError" | "strict" + | "AssertionError" > & { (value: unknown, message?: string | Error): asserts value; @@ -1030,6 +1043,7 @@ declare module "assert" { deepStrictEqual: typeof deepStrictEqual; ifError: typeof ifError; strict: typeof strict; + AssertionError: typeof AssertionError; }; } export = assert; diff --git a/node_modules/@types/node/async_hooks.d.ts b/node_modules/@types/node/async_hooks.d.ts index 4d6df8150..01d21d4b0 100644 --- a/node_modules/@types/node/async_hooks.d.ts +++ b/node_modules/@types/node/async_hooks.d.ts @@ -358,8 +358,8 @@ declare module "async_hooks" { * http.get('http://localhost:8080'); * // Prints: * // 0: start - * // 1: start * // 0: finish + * // 1: start * // 1: finish * ``` * @@ -372,7 +372,6 @@ declare module "async_hooks" { /** * Binds the given function to the current execution context. * @since v19.8.0 - * @experimental * @param fn The function to bind to the current execution context. * @return A new function that calls `fn` within the captured execution context. */ @@ -403,7 +402,6 @@ declare module "async_hooks" { * console.log(asyncLocalStorage.run(321, () => foo.get())); // returns 123 * ``` * @since v19.8.0 - * @experimental * @return A new function with the signature `(fn: (...args) : R, ...args) : R`. */ static snapshot(): (fn: (...args: TArgs) => R, ...args: TArgs) => R; @@ -535,6 +533,70 @@ declare module "async_hooks" { */ enterWith(store: T): void; } + /** + * @since v17.2.0, v16.14.0 + * @return A map of provider types to the corresponding numeric id. + * This map contains all the event types that might be emitted by the `async_hooks.init()` event. + */ + namespace asyncWrapProviders { + const NONE: number; + const DIRHANDLE: number; + const DNSCHANNEL: number; + const ELDHISTOGRAM: number; + const FILEHANDLE: number; + const FILEHANDLECLOSEREQ: number; + const FIXEDSIZEBLOBCOPY: number; + const FSEVENTWRAP: number; + const FSREQCALLBACK: number; + const FSREQPROMISE: number; + const GETADDRINFOREQWRAP: number; + const GETNAMEINFOREQWRAP: number; + const HEAPSNAPSHOT: number; + const HTTP2SESSION: number; + const HTTP2STREAM: number; + const HTTP2PING: number; + const HTTP2SETTINGS: number; + const HTTPINCOMINGMESSAGE: number; + const HTTPCLIENTREQUEST: number; + const JSSTREAM: number; + const JSUDPWRAP: number; + const MESSAGEPORT: number; + const PIPECONNECTWRAP: number; + const PIPESERVERWRAP: number; + const PIPEWRAP: number; + const PROCESSWRAP: number; + const PROMISE: number; + const QUERYWRAP: number; + const SHUTDOWNWRAP: number; + const SIGNALWRAP: number; + const STATWATCHER: number; + const STREAMPIPE: number; + const TCPCONNECTWRAP: number; + const TCPSERVERWRAP: number; + const TCPWRAP: number; + const TTYWRAP: number; + const UDPSENDWRAP: number; + const UDPWRAP: number; + const SIGINTWATCHDOG: number; + const WORKER: number; + const WORKERHEAPSNAPSHOT: number; + const WRITEWRAP: number; + const ZLIB: number; + const CHECKPRIMEREQUEST: number; + const PBKDF2REQUEST: number; + const KEYPAIRGENREQUEST: number; + const KEYGENREQUEST: number; + const KEYEXPORTREQUEST: number; + const CIPHERREQUEST: number; + const DERIVEBITSREQUEST: number; + const HASHREQUEST: number; + const RANDOMBYTESREQUEST: number; + const RANDOMPRIMEREQUEST: number; + const SCRYPTREQUEST: number; + const SIGNREQUEST: number; + const TLSWRAP: number; + const VERIFYREQUEST: number; + } } declare module "node:async_hooks" { export * from "async_hooks"; diff --git a/node_modules/@types/node/buffer.buffer.d.ts b/node_modules/@types/node/buffer.buffer.d.ts index 0b6c49a64..b22f83a29 100644 --- a/node_modules/@types/node/buffer.buffer.d.ts +++ b/node_modules/@types/node/buffer.buffer.d.ts @@ -1,4 +1,6 @@ declare module "buffer" { + type ImplicitArrayBuffer> = T extends + { valueOf(): infer V extends ArrayBufferLike } ? V : T; global { interface BufferConstructor { // see buffer.d.ts for implementation shared with all TypeScript versions @@ -24,7 +26,7 @@ declare module "buffer" { * @param array The octets to store. * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead. */ - new(array: Uint8Array): Buffer; + new(array: ArrayLike): Buffer; /** * Produces a Buffer backed by the same allocated memory as * the given {ArrayBuffer}/{SharedArrayBuffer}. @@ -33,20 +35,6 @@ declare module "buffer" { * @deprecated since v10.0.0 - Use `Buffer.from(arrayBuffer[, byteOffset[, length]])` instead. */ new(arrayBuffer: TArrayBuffer): Buffer; - /** - * Allocates a new buffer containing the given {array} of octets. - * - * @param array The octets to store. - * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead. - */ - new(array: readonly any[]): Buffer; - /** - * Copies the passed {buffer} data onto a new {Buffer} instance. - * - * @param buffer The buffer to copy. - * @deprecated since v10.0.0 - Use `Buffer.from(buffer)` instead. - */ - new(buffer: Buffer): Buffer; /** * Allocates a new `Buffer` using an `array` of bytes in the range `0` – `255`. * Array entries outside that range will be truncated to fit into it. @@ -58,40 +46,121 @@ declare module "buffer" { * const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); * ``` * - * If `array` is an `Array`\-like object (that is, one with a `length` property of + * If `array` is an `Array`-like object (that is, one with a `length` property of * type `number`), it is treated as if it is an array, unless it is a `Buffer` or - * a `Uint8Array`. This means all other `TypedArray` variants get treated as an `Array`. To create a `Buffer` from the bytes backing a `TypedArray`, use `Buffer.copyBytesFrom()`. + * a `Uint8Array`. This means all other `TypedArray` variants get treated as an + * `Array`. To create a `Buffer` from the bytes backing a `TypedArray`, use + * `Buffer.copyBytesFrom()`. * * A `TypeError` will be thrown if `array` is not an `Array` or another type * appropriate for `Buffer.from()` variants. * - * `Buffer.from(array)` and `Buffer.from(string)` may also use the internal `Buffer` pool like `Buffer.allocUnsafe()` does. + * `Buffer.from(array)` and `Buffer.from(string)` may also use the internal + * `Buffer` pool like `Buffer.allocUnsafe()` does. * @since v5.10.0 */ - from( - arrayBuffer: WithImplicitCoercion, - byteOffset?: number, - length?: number, - ): Buffer; + from(array: WithImplicitCoercion>): Buffer; /** - * Creates a new Buffer using the passed {data} - * @param data data to create a new Buffer + * This creates a view of the `ArrayBuffer` without copying the underlying + * memory. For example, when passed a reference to the `.buffer` property of a + * `TypedArray` instance, the newly created `Buffer` will share the same + * allocated memory as the `TypedArray`'s underlying `ArrayBuffer`. + * + * ```js + * import { Buffer } from 'node:buffer'; + * + * const arr = new Uint16Array(2); + * + * arr[0] = 5000; + * arr[1] = 4000; + * + * // Shares memory with `arr`. + * const buf = Buffer.from(arr.buffer); + * + * console.log(buf); + * // Prints: + * + * // Changing the original Uint16Array changes the Buffer also. + * arr[1] = 6000; + * + * console.log(buf); + * // Prints: + * ``` + * + * The optional `byteOffset` and `length` arguments specify a memory range within + * the `arrayBuffer` that will be shared by the `Buffer`. + * + * ```js + * import { Buffer } from 'node:buffer'; + * + * const ab = new ArrayBuffer(10); + * const buf = Buffer.from(ab, 0, 2); + * + * console.log(buf.length); + * // Prints: 2 + * ``` + * + * A `TypeError` will be thrown if `arrayBuffer` is not an `ArrayBuffer` or a + * `SharedArrayBuffer` or another type appropriate for `Buffer.from()` + * variants. + * + * It is important to remember that a backing `ArrayBuffer` can cover a range + * of memory that extends beyond the bounds of a `TypedArray` view. A new + * `Buffer` created using the `buffer` property of a `TypedArray` may extend + * beyond the range of the `TypedArray`: + * + * ```js + * import { Buffer } from 'node:buffer'; + * + * const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 elements + * const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 elements + * console.log(arrA.buffer === arrB.buffer); // true + * + * const buf = Buffer.from(arrB.buffer); + * console.log(buf); + * // Prints: + * ``` + * @since v5.10.0 + * @param arrayBuffer An `ArrayBuffer`, `SharedArrayBuffer`, for example the + * `.buffer` property of a `TypedArray`. + * @param byteOffset Index of first byte to expose. **Default:** `0`. + * @param length Number of bytes to expose. **Default:** + * `arrayBuffer.byteLength - byteOffset`. */ - from(data: Uint8Array | readonly number[]): Buffer; - from(data: WithImplicitCoercion): Buffer; + from>( + arrayBuffer: TArrayBuffer, + byteOffset?: number, + length?: number, + ): Buffer>; /** - * Creates a new Buffer containing the given JavaScript string {str}. - * If provided, the {encoding} parameter identifies the character encoding. - * If not provided, {encoding} defaults to 'utf8'. + * Creates a new `Buffer` containing `string`. The `encoding` parameter identifies + * the character encoding to be used when converting `string` into bytes. + * + * ```js + * import { Buffer } from 'node:buffer'; + * + * const buf1 = Buffer.from('this is a tést'); + * const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex'); + * + * console.log(buf1.toString()); + * // Prints: this is a tést + * console.log(buf2.toString()); + * // Prints: this is a tést + * console.log(buf1.toString('latin1')); + * // Prints: this is a tést + * ``` + * + * A `TypeError` will be thrown if `string` is not a string or another type + * appropriate for `Buffer.from()` variants. + * + * `Buffer.from(string)` may also use the internal `Buffer` pool like + * `Buffer.allocUnsafe()` does. + * @since v5.10.0 + * @param string A string to encode. + * @param encoding The encoding of `string`. **Default:** `'utf8'`. */ - from( - str: - | WithImplicitCoercion - | { - [Symbol.toPrimitive](hint: "string"): string; - }, - encoding?: BufferEncoding, - ): Buffer; + from(string: WithImplicitCoercion, encoding?: BufferEncoding): Buffer; + from(arrayOrString: WithImplicitCoercion | string>): Buffer; /** * Creates a new Buffer using the passed {data} * @param values to create a new Buffer @@ -107,7 +176,8 @@ declare module "buffer" { * * If `totalLength` is provided, it is coerced to an unsigned integer. If the * combined length of the `Buffer`s in `list` exceeds `totalLength`, the result is - * truncated to `totalLength`. + * truncated to `totalLength`. If the combined length of the `Buffer`s in `list` is + * less than `totalLength`, the remaining space is filled with zeros. * * ```js * import { Buffer } from 'node:buffer'; @@ -381,5 +451,13 @@ declare module "buffer" { */ subarray(start?: number, end?: number): Buffer; } + type NonSharedBuffer = Buffer; + type AllowSharedBuffer = Buffer; } + /** @deprecated Use `Buffer.allocUnsafeSlow()` instead. */ + var SlowBuffer: { + /** @deprecated Use `Buffer.allocUnsafeSlow()` instead. */ + new(size: number): Buffer; + prototype: Buffer; + }; } diff --git a/node_modules/@types/node/buffer.d.ts b/node_modules/@types/node/buffer.d.ts index 792bf4d75..2a561c06b 100644 --- a/node_modules/@types/node/buffer.d.ts +++ b/node_modules/@types/node/buffer.d.ts @@ -69,7 +69,7 @@ declare module "buffer" { * @param input The input to validate. */ export function isAscii(input: Buffer | ArrayBuffer | NodeJS.TypedArray): boolean; - export const INSPECT_MAX_BYTES: number; + export let INSPECT_MAX_BYTES: number; export const kMaxLength: number; export const kStringMaxLength: number; export const constants: { @@ -114,20 +114,14 @@ declare module "buffer" { * @param toEnc To target encoding. */ export function transcode(source: Uint8Array, fromEnc: TranscodeEncoding, toEnc: TranscodeEncoding): Buffer; - export const SlowBuffer: { - /** @deprecated since v6.0.0, use `Buffer.allocUnsafeSlow()` */ - new(size: number): Buffer; - prototype: Buffer; - }; /** * Resolves a `'blob:nodedata:...'` an associated `Blob` object registered using * a prior call to `URL.createObjectURL()`. * @since v16.7.0 - * @experimental * @param id A `'blob:nodedata:...` URL string returned by a prior call to `URL.createObjectURL()`. */ export function resolveObjectURL(id: string): Blob | undefined; - export { Buffer }; + export { type AllowSharedBuffer, Buffer, type NonSharedBuffer }; /** * @experimental */ @@ -237,7 +231,10 @@ declare module "buffer" { } export import atob = globalThis.atob; export import btoa = globalThis.btoa; - + export type WithImplicitCoercion = + | T + | { valueOf(): T } + | (T extends string ? { [Symbol.toPrimitive](hint: "string"): T } : never); global { namespace NodeJS { export { BufferEncoding }; @@ -256,11 +253,6 @@ declare module "buffer" { | "latin1" | "binary" | "hex"; - type WithImplicitCoercion = - | T - | { - valueOf(): T; - }; /** * Raw data is stored in instances of the Buffer class. * A Buffer is similar to an array of integers but corresponds to a raw memory allocation outside the V8 heap. A Buffer cannot be resized. @@ -1709,6 +1701,8 @@ declare module "buffer" { * @return A reference to `buf`. */ fill(value: string | Uint8Array | number, offset?: number, end?: number, encoding?: BufferEncoding): this; + fill(value: string | Uint8Array | number, offset: number, encoding: BufferEncoding): this; + fill(value: string | Uint8Array | number, encoding: BufferEncoding): this; /** * If `value` is: * @@ -1778,6 +1772,7 @@ declare module "buffer" { * @return The index of the first occurrence of `value` in `buf`, or `-1` if `buf` does not contain `value`. */ indexOf(value: string | number | Uint8Array, byteOffset?: number, encoding?: BufferEncoding): number; + indexOf(value: string | number | Uint8Array, encoding: BufferEncoding): number; /** * Identical to `buf.indexOf()`, except the last occurrence of `value` is found * rather than the first occurrence. @@ -1846,6 +1841,7 @@ declare module "buffer" { * @return The index of the last occurrence of `value` in `buf`, or `-1` if `buf` does not contain `value`. */ lastIndexOf(value: string | number | Uint8Array, byteOffset?: number, encoding?: BufferEncoding): number; + lastIndexOf(value: string | number | Uint8Array, encoding: BufferEncoding): number; /** * Equivalent to `buf.indexOf() !== -1`. * @@ -1876,6 +1872,7 @@ declare module "buffer" { * @return `true` if `value` was found in `buf`, `false` otherwise. */ includes(value: string | number | Buffer, byteOffset?: number, encoding?: BufferEncoding): boolean; + includes(value: string | number | Buffer, encoding: BufferEncoding): boolean; } var Buffer: BufferConstructor; /** diff --git a/node_modules/@types/node/child_process.d.ts b/node_modules/@types/node/child_process.d.ts index 09f181f92..644f4288a 100644 --- a/node_modules/@types/node/child_process.d.ts +++ b/node_modules/@types/node/child_process.d.ts @@ -66,7 +66,6 @@ * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/child_process.js) */ declare module "child_process" { - import { ObjectEncodingOptions } from "node:fs"; import { Abortable, EventEmitter } from "node:events"; import * as dgram from "node:dgram"; import * as net from "node:net"; @@ -887,12 +886,13 @@ declare module "child_process" { signal?: AbortSignal | undefined; maxBuffer?: number | undefined; killSignal?: NodeJS.Signals | number | undefined; + encoding?: string | null | undefined; } interface ExecOptionsWithStringEncoding extends ExecOptions { - encoding: BufferEncoding; + encoding?: BufferEncoding | undefined; } interface ExecOptionsWithBufferEncoding extends ExecOptions { - encoding: BufferEncoding | null; // specify `null`. + encoding: "buffer" | null; // specify `null`. } interface ExecException extends Error { cmd?: string | undefined; @@ -995,38 +995,19 @@ declare module "child_process" { // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`. function exec( command: string, - options: { - encoding: "buffer" | null; - } & ExecOptions, + options: ExecOptionsWithBufferEncoding, callback?: (error: ExecException | null, stdout: Buffer, stderr: Buffer) => void, ): ChildProcess; - // `options` with well known `encoding` means stdout/stderr are definitely `string`. - function exec( - command: string, - options: { - encoding: BufferEncoding; - } & ExecOptions, - callback?: (error: ExecException | null, stdout: string, stderr: string) => void, - ): ChildProcess; - // `options` with an `encoding` whose type is `string` means stdout/stderr could either be `Buffer` or `string`. - // There is no guarantee the `encoding` is unknown as `string` is a superset of `BufferEncoding`. - function exec( - command: string, - options: { - encoding: BufferEncoding; - } & ExecOptions, - callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void, - ): ChildProcess; - // `options` without an `encoding` means stdout/stderr are definitely `string`. + // `options` with well-known or absent `encoding` means stdout/stderr are definitely `string`. function exec( command: string, - options: ExecOptions, + options: ExecOptionsWithStringEncoding, callback?: (error: ExecException | null, stdout: string, stderr: string) => void, ): ChildProcess; // fallback if nothing else matches. Worst case is always `string | Buffer`. function exec( command: string, - options: (ObjectEncodingOptions & ExecOptions) | undefined | null, + options: ExecOptions | undefined | null, callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void, ): ChildProcess; interface PromiseWithChild extends Promise { @@ -1039,32 +1020,21 @@ declare module "child_process" { }>; function __promisify__( command: string, - options: { - encoding: "buffer" | null; - } & ExecOptions, + options: ExecOptionsWithBufferEncoding, ): PromiseWithChild<{ stdout: Buffer; stderr: Buffer; }>; function __promisify__( command: string, - options: { - encoding: BufferEncoding; - } & ExecOptions, + options: ExecOptionsWithStringEncoding, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( command: string, - options: ExecOptions, - ): PromiseWithChild<{ - stdout: string; - stderr: string; - }>; - function __promisify__( - command: string, - options?: (ObjectEncodingOptions & ExecOptions) | null, + options: ExecOptions | undefined | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; @@ -1076,16 +1046,16 @@ declare module "child_process" { windowsVerbatimArguments?: boolean | undefined; shell?: boolean | string | undefined; signal?: AbortSignal | undefined; + encoding?: string | null | undefined; } interface ExecFileOptionsWithStringEncoding extends ExecFileOptions { - encoding: BufferEncoding; + encoding?: BufferEncoding | undefined; } interface ExecFileOptionsWithBufferEncoding extends ExecFileOptions { encoding: "buffer" | null; } - interface ExecFileOptionsWithOtherEncoding extends ExecFileOptions { - encoding: BufferEncoding; - } + /** @deprecated Use `ExecFileOptions` instead. */ + interface ExecFileOptionsWithOtherEncoding extends ExecFileOptions {} type ExecFileException = & Omit & Omit @@ -1154,80 +1124,44 @@ declare module "child_process" { * @param args List of string arguments. * @param callback Called with the output when process terminates. */ - function execFile(file: string): ChildProcess; - function execFile( - file: string, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, - ): ChildProcess; - function execFile(file: string, args?: readonly string[] | null): ChildProcess; - function execFile( - file: string, - args: readonly string[] | undefined | null, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, - ): ChildProcess; // no `options` definitely means stdout/stderr are `string`. function execFile( file: string, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + callback?: (error: ExecFileException | null, stdout: string, stderr: string) => void, ): ChildProcess; function execFile( file: string, args: readonly string[] | undefined | null, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + callback?: (error: ExecFileException | null, stdout: string, stderr: string) => void, ): ChildProcess; // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`. function execFile( file: string, options: ExecFileOptionsWithBufferEncoding, - callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void, + callback?: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void, ): ChildProcess; function execFile( file: string, args: readonly string[] | undefined | null, options: ExecFileOptionsWithBufferEncoding, - callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void, + callback?: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void, ): ChildProcess; - // `options` with well known `encoding` means stdout/stderr are definitely `string`. + // `options` with well-known or absent `encoding` means stdout/stderr are definitely `string`. function execFile( file: string, options: ExecFileOptionsWithStringEncoding, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + callback?: (error: ExecFileException | null, stdout: string, stderr: string) => void, ): ChildProcess; function execFile( file: string, args: readonly string[] | undefined | null, options: ExecFileOptionsWithStringEncoding, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, - ): ChildProcess; - // `options` with an `encoding` whose type is `string` means stdout/stderr could either be `Buffer` or `string`. - // There is no guarantee the `encoding` is unknown as `string` is a superset of `BufferEncoding`. - function execFile( - file: string, - options: ExecFileOptionsWithOtherEncoding, - callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void, - ): ChildProcess; - function execFile( - file: string, - args: readonly string[] | undefined | null, - options: ExecFileOptionsWithOtherEncoding, - callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void, - ): ChildProcess; - // `options` without an `encoding` means stdout/stderr are definitely `string`. - function execFile( - file: string, - options: ExecFileOptions, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, - ): ChildProcess; - function execFile( - file: string, - args: readonly string[] | undefined | null, - options: ExecFileOptions, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + callback?: (error: ExecFileException | null, stdout: string, stderr: string) => void, ): ChildProcess; // fallback if nothing else matches. Worst case is always `string | Buffer`. function execFile( file: string, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, + options: ExecFileOptions | undefined | null, callback: | ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) | undefined @@ -1236,7 +1170,7 @@ declare module "child_process" { function execFile( file: string, args: readonly string[] | undefined | null, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, + options: ExecFileOptions | undefined | null, callback: | ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) | undefined @@ -1286,37 +1220,7 @@ declare module "child_process" { }>; function __promisify__( file: string, - options: ExecFileOptionsWithOtherEncoding, - ): PromiseWithChild<{ - stdout: string | Buffer; - stderr: string | Buffer; - }>; - function __promisify__( - file: string, - args: readonly string[] | undefined | null, - options: ExecFileOptionsWithOtherEncoding, - ): PromiseWithChild<{ - stdout: string | Buffer; - stderr: string | Buffer; - }>; - function __promisify__( - file: string, - options: ExecFileOptions, - ): PromiseWithChild<{ - stdout: string; - stderr: string; - }>; - function __promisify__( - file: string, - args: readonly string[] | undefined | null, - options: ExecFileOptions, - ): PromiseWithChild<{ - stdout: string; - stderr: string; - }>; - function __promisify__( - file: string, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, + options: ExecFileOptions | undefined | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; @@ -1324,7 +1228,7 @@ declare module "child_process" { function __promisify__( file: string, args: readonly string[] | undefined | null, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, + options: ExecFileOptions | undefined | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; diff --git a/node_modules/@types/node/cluster.d.ts b/node_modules/@types/node/cluster.d.ts index 86b48d9b2..92743ebdd 100644 --- a/node_modules/@types/node/cluster.d.ts +++ b/node_modules/@types/node/cluster.d.ts @@ -266,7 +266,7 @@ declare module "cluster" { * @since v0.7.7 * @return A reference to `worker`. */ - disconnect(): void; + disconnect(): this; /** * This function returns `true` if the worker is connected to its primary via its * IPC channel, `false` otherwise. A worker is connected to its primary after it diff --git a/node_modules/@types/node/compatibility/disposable.d.ts b/node_modules/@types/node/compatibility/disposable.d.ts index 5fff612b5..e23d5a7c4 100644 --- a/node_modules/@types/node/compatibility/disposable.d.ts +++ b/node_modules/@types/node/compatibility/disposable.d.ts @@ -1,6 +1,4 @@ // Polyfills for the explicit resource management types added in TypeScript 5.2. -// TODO: remove once this package no longer supports TS 5.1, and replace with a -// to TypeScript's disposable library in index.d.ts. interface SymbolConstructor { readonly dispose: unique symbol; diff --git a/node_modules/@types/node/compatibility/indexable.d.ts b/node_modules/@types/node/compatibility/indexable.d.ts index 99197029c..262ba09ce 100644 --- a/node_modules/@types/node/compatibility/indexable.d.ts +++ b/node_modules/@types/node/compatibility/indexable.d.ts @@ -1,7 +1,4 @@ // Polyfill for ES2022's .at() method on string/array prototypes, added to TypeScript in 4.6. -// TODO: these methods are not used within @types/node, and should be removed at the next -// major @types/node version; users should include the es2022 TypeScript libraries -// if they need these features. interface RelativeIndexable { at(index: number): T | undefined; diff --git a/node_modules/@types/node/compatibility/iterators.d.ts b/node_modules/@types/node/compatibility/iterators.d.ts index 156e78563..2f9be9cd6 100644 --- a/node_modules/@types/node/compatibility/iterators.d.ts +++ b/node_modules/@types/node/compatibility/iterators.d.ts @@ -3,7 +3,6 @@ // are expected (eg. DOM-compatible APIs) if lib.esnext.iterator is loaded. // Also ensures that iterators returned by the Node API, which inherit from Iterator.prototype, correctly expose the iterator helper methods // if lib.esnext.iterator is loaded. -// TODO: remove once this package no longer supports TS 5.5, and replace NodeJS.BuiltinIteratorReturn with BuiltinIteratorReturn. // Placeholders for TS <5.6 interface IteratorObject {} diff --git a/node_modules/@types/node/constants.d.ts b/node_modules/@types/node/constants.d.ts index c3ac2b826..5685a9dfe 100644 --- a/node_modules/@types/node/constants.d.ts +++ b/node_modules/@types/node/constants.d.ts @@ -1,16 +1,18 @@ -/** @deprecated since v6.3.0 - use constants property exposed by the relevant module instead. */ +/** + * @deprecated The `node:constants` module is deprecated. When requiring access to constants + * relevant to specific Node.js builtin modules, developers should instead refer + * to the `constants` property exposed by the relevant module. For instance, + * `require('node:fs').constants` and `require('node:os').constants`. + */ declare module "constants" { - import { constants as osConstants, SignalConstants } from "node:os"; - import { constants as cryptoConstants } from "node:crypto"; - import { constants as fsConstants } from "node:fs"; - - const exp: - & typeof osConstants.errno - & typeof osConstants.priority - & SignalConstants - & typeof cryptoConstants - & typeof fsConstants; - export = exp; + const constants: + & typeof import("node:os").constants.dlopen + & typeof import("node:os").constants.errno + & typeof import("node:os").constants.priority + & typeof import("node:os").constants.signals + & typeof import("node:fs").constants + & typeof import("node:crypto").constants; + export = constants; } declare module "node:constants" { diff --git a/node_modules/@types/node/crypto.d.ts b/node_modules/@types/node/crypto.d.ts index 9b6bcf81d..859d4c490 100644 --- a/node_modules/@types/node/crypto.d.ts +++ b/node_modules/@types/node/crypto.d.ts @@ -609,11 +609,6 @@ declare module "crypto" { * @since v11.6.0 */ asymmetricKeyType?: KeyType | undefined; - /** - * For asymmetric keys, this property represents the size of the embedded key in - * bytes. This property is `undefined` for symmetric keys. - */ - asymmetricKeySize?: number | undefined; /** * This property exists only on asymmetric keys. Depending on the type of the key, * this object contains information about the key. None of the information obtained @@ -667,6 +662,19 @@ declare module "crypto" { * @since v11.6.0 */ symmetricKeySize?: number | undefined; + /** + * Converts a `KeyObject` instance to a `CryptoKey`. + * @since 22.10.0 + */ + toCryptoKey( + algorithm: + | webcrypto.AlgorithmIdentifier + | webcrypto.RsaHashedImportParams + | webcrypto.EcKeyImportParams + | webcrypto.HmacImportParams, + extractable: boolean, + keyUsages: readonly webcrypto.KeyUsage[], + ): webcrypto.CryptoKey; /** * Depending on the type of this `KeyObject`, this property is either`'secret'` for secret (symmetric) keys, `'public'` for public (asymmetric) keys * or `'private'` for private (asymmetric) keys. @@ -674,9 +682,10 @@ declare module "crypto" { */ type: KeyObjectType; } - type CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm" | "chacha20-poly1305"; + type CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm"; type CipherGCMTypes = "aes-128-gcm" | "aes-192-gcm" | "aes-256-gcm"; type CipherOCBTypes = "aes-128-ocb" | "aes-192-ocb" | "aes-256-ocb"; + type CipherChaCha20Poly1305Types = "chacha20-poly1305"; type BinaryLike = string | NodeJS.ArrayBufferView; type CipherKey = BinaryLike | KeyObject; interface CipherCCMOptions extends stream.TransformOptions { @@ -688,6 +697,10 @@ declare module "crypto" { interface CipherOCBOptions extends stream.TransformOptions { authTagLength: number; } + interface CipherChaCha20Poly1305Options extends stream.TransformOptions { + /** @default 16 */ + authTagLength?: number | undefined; + } /** * Creates and returns a `Cipher` object, with the given `algorithm`, `key` and * initialization vector (`iv`). @@ -736,6 +749,12 @@ declare module "crypto" { iv: BinaryLike, options?: CipherGCMOptions, ): CipherGCM; + function createCipheriv( + algorithm: CipherChaCha20Poly1305Types, + key: CipherKey, + iv: BinaryLike, + options?: CipherChaCha20Poly1305Options, + ): CipherChaCha20Poly1305; function createCipheriv( algorithm: string, key: CipherKey, @@ -935,6 +954,15 @@ declare module "crypto" { ): this; getAuthTag(): Buffer; } + interface CipherChaCha20Poly1305 extends Cipher { + setAAD( + buffer: NodeJS.ArrayBufferView, + options: { + plaintextLength: number; + }, + ): this; + getAuthTag(): Buffer; + } /** * Creates and returns a `Decipher` object that uses the given `algorithm`, `key` and initialization vector (`iv`). * @@ -982,6 +1010,12 @@ declare module "crypto" { iv: BinaryLike, options?: CipherGCMOptions, ): DecipherGCM; + function createDecipheriv( + algorithm: CipherChaCha20Poly1305Types, + key: CipherKey, + iv: BinaryLike, + options?: CipherChaCha20Poly1305Options, + ): DecipherChaCha20Poly1305; function createDecipheriv( algorithm: string, key: CipherKey, @@ -1167,6 +1201,15 @@ declare module "crypto" { }, ): this; } + interface DecipherChaCha20Poly1305 extends Decipher { + setAuthTag(buffer: NodeJS.ArrayBufferView): this; + setAAD( + buffer: NodeJS.ArrayBufferView, + options: { + plaintextLength: number; + }, + ): this; + } interface PrivateKeyInput { key: string | Buffer; format?: KeyFormat | undefined; @@ -2139,7 +2182,10 @@ declare module "crypto" { * be passed instead of a public key. * @since v0.11.14 */ - function publicEncrypt(key: RsaPublicKey | RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView): Buffer; + function publicEncrypt( + key: RsaPublicKey | RsaPrivateKey | KeyLike, + buffer: NodeJS.ArrayBufferView | string, + ): Buffer; /** * Decrypts `buffer` with `key`.`buffer` was previously encrypted using * the corresponding private key, for example using {@link privateEncrypt}. @@ -2151,7 +2197,10 @@ declare module "crypto" { * be passed instead of a public key. * @since v1.1.0 */ - function publicDecrypt(key: RsaPublicKey | RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView): Buffer; + function publicDecrypt( + key: RsaPublicKey | RsaPrivateKey | KeyLike, + buffer: NodeJS.ArrayBufferView | string, + ): Buffer; /** * Decrypts `buffer` with `privateKey`. `buffer` was previously encrypted using * the corresponding public key, for example using {@link publicEncrypt}. @@ -2160,7 +2209,7 @@ declare module "crypto" { * object, the `padding` property can be passed. Otherwise, this function uses `RSA_PKCS1_OAEP_PADDING`. * @since v0.11.14 */ - function privateDecrypt(privateKey: RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView): Buffer; + function privateDecrypt(privateKey: RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer; /** * Encrypts `buffer` with `privateKey`. The returned data can be decrypted using * the corresponding public key, for example using {@link publicDecrypt}. @@ -2169,7 +2218,7 @@ declare module "crypto" { * object, the `padding` property can be passed. Otherwise, this function uses `RSA_PKCS1_PADDING`. * @since v1.1.0 */ - function privateEncrypt(privateKey: RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView): Buffer; + function privateEncrypt(privateKey: RsaPrivateKey | KeyLike, buffer: NodeJS.ArrayBufferView | string): Buffer; /** * ```js * const { @@ -3648,11 +3697,21 @@ declare module "crypto" { * @since v15.6.0 */ readonly validFrom: string; + /** + * The date/time from which this certificate is valid, encapsulated in a `Date` object. + * @since v22.10.0 + */ + readonly validFromDate: Date; /** * The date/time until which this certificate is considered valid. * @since v15.6.0 */ readonly validTo: string; + /** + * The date/time until which this certificate is valid, encapsulated in a `Date` object. + * @since v22.10.0 + */ + readonly validToDate: Date; constructor(buffer: BinaryLike); /** * Checks whether the certificate matches the given email address. @@ -3705,7 +3764,23 @@ declare module "crypto" { */ checkIP(ip: string): string | undefined; /** - * Checks whether this certificate was issued by the given `otherCert`. + * Checks whether this certificate was potentially issued by the given `otherCert` + * by comparing the certificate metadata. + * + * This is useful for pruning a list of possible issuer certificates which have been + * selected using a more rudimentary filtering routine, i.e. just based on subject + * and issuer names. + * + * Finally, to verify that this certificate's signature was produced by a private key + * corresponding to `otherCert`'s public key use `x509.verify(publicKey)` + * with `otherCert`'s public key represented as a `KeyObject` + * like so + * + * ```js + * if (!x509.verify(otherCert.publicKey)) { + * throw new Error('otherCert did not issue x509'); + * } + * ``` * @since v15.6.0 */ checkIssued(otherCert: X509Certificate): boolean; @@ -4162,9 +4237,13 @@ declare module "crypto" { * - `'PBKDF2'` * @since v15.0.0 */ - deriveBits(algorithm: EcdhKeyDeriveParams, baseKey: CryptoKey, length: number | null): Promise; deriveBits( - algorithm: AlgorithmIdentifier | HkdfParams | Pbkdf2Params, + algorithm: EcdhKeyDeriveParams, + baseKey: CryptoKey, + length?: number | null, + ): Promise; + deriveBits( + algorithm: EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params, baseKey: CryptoKey, length: number, ): Promise; @@ -4186,14 +4265,9 @@ declare module "crypto" { * @since v15.0.0 */ deriveKey( - algorithm: AlgorithmIdentifier | EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params, + algorithm: EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params, baseKey: CryptoKey, - derivedKeyAlgorithm: - | AlgorithmIdentifier - | AesDerivedKeyParams - | HmacImportParams - | HkdfParams - | Pbkdf2Params, + derivedKeyAlgorithm: AlgorithmIdentifier | HmacImportParams | AesDerivedKeyParams, extractable: boolean, keyUsages: readonly KeyUsage[], ): Promise; diff --git a/node_modules/@types/node/dgram.d.ts b/node_modules/@types/node/dgram.d.ts index 8c2ac9b7c..77a851f36 100644 --- a/node_modules/@types/node/dgram.d.ts +++ b/node_modules/@types/node/dgram.d.ts @@ -26,7 +26,7 @@ * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/dgram.js) */ declare module "dgram" { - import { AddressInfo } from "node:net"; + import { AddressInfo, BlockList } from "node:net"; import * as dns from "node:dns"; import { Abortable, EventEmitter } from "node:events"; interface RemoteInfo { @@ -45,6 +45,7 @@ declare module "dgram" { interface SocketOptions extends Abortable { type: SocketType; reuseAddr?: boolean | undefined; + reusePort?: boolean | undefined; /** * @default false */ @@ -58,6 +59,8 @@ declare module "dgram" { callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, ) => void) | undefined; + receiveBlockList?: BlockList | undefined; + sendBlockList?: BlockList | undefined; } /** * Creates a `dgram.Socket` object. Once the socket is created, calling `socket.bind()` will instruct the socket to begin listening for datagram @@ -352,22 +355,22 @@ declare module "dgram" { * @param callback Called when the message has been sent. */ send( - msg: string | Uint8Array | readonly any[], + msg: string | NodeJS.ArrayBufferView | readonly any[], port?: number, address?: string, callback?: (error: Error | null, bytes: number) => void, ): void; send( - msg: string | Uint8Array | readonly any[], + msg: string | NodeJS.ArrayBufferView | readonly any[], port?: number, callback?: (error: Error | null, bytes: number) => void, ): void; send( - msg: string | Uint8Array | readonly any[], + msg: string | NodeJS.ArrayBufferView | readonly any[], callback?: (error: Error | null, bytes: number) => void, ): void; send( - msg: string | Uint8Array, + msg: string | NodeJS.ArrayBufferView, offset: number, length: number, port?: number, @@ -375,14 +378,14 @@ declare module "dgram" { callback?: (error: Error | null, bytes: number) => void, ): void; send( - msg: string | Uint8Array, + msg: string | NodeJS.ArrayBufferView, offset: number, length: number, port?: number, callback?: (error: Error | null, bytes: number) => void, ): void; send( - msg: string | Uint8Array, + msg: string | NodeJS.ArrayBufferView, offset: number, length: number, callback?: (error: Error | null, bytes: number) => void, diff --git a/node_modules/@types/node/diagnostics_channel.d.ts b/node_modules/@types/node/diagnostics_channel.d.ts index 1cc7486b4..f3bac5277 100644 --- a/node_modules/@types/node/diagnostics_channel.d.ts +++ b/node_modules/@types/node/diagnostics_channel.d.ts @@ -259,7 +259,7 @@ declare module "diagnostics_channel" { * @param store The store to unbind from the channel. * @return `true` if the store was found, `false` otherwise. */ - unbindStore(store: any): void; + unbindStore(store: AsyncLocalStorage): boolean; /** * Applies the given data to any AsyncLocalStorage instances bound to the channel * for the duration of the given function, then publishes to the channel within @@ -297,7 +297,12 @@ declare module "diagnostics_channel" { * @param thisArg The receiver to be used for the function call. * @param args Optional arguments to pass to the function. */ - runStores(): void; + runStores( + context: ContextType, + fn: (this: ThisArg, ...args: Args) => Result, + thisArg?: ThisArg, + ...args: Args + ): Result; } interface TracingChannelSubscribers { start: (message: ContextType) => void; @@ -441,12 +446,12 @@ declare module "diagnostics_channel" { * @param args Optional arguments to pass to the function * @return The return value of the given function */ - traceSync( - fn: (this: ThisArg, ...args: Args) => any, + traceSync( + fn: (this: ThisArg, ...args: Args) => Result, context?: ContextType, thisArg?: ThisArg, ...args: Args - ): void; + ): Result; /** * Trace a promise-returning function call. This will always produce a `start event` and `end event` around the synchronous portion of the * function execution, and will produce an `asyncStart event` and `asyncEnd event` when a promise continuation is reached. It may also @@ -476,12 +481,12 @@ declare module "diagnostics_channel" { * @param args Optional arguments to pass to the function * @return Chained from promise returned by the given function */ - tracePromise( - fn: (this: ThisArg, ...args: Args) => Promise, + tracePromise( + fn: (this: ThisArg, ...args: Args) => Promise, context?: ContextType, thisArg?: ThisArg, ...args: Args - ): void; + ): Promise; /** * Trace a callback-receiving function call. This will always produce a `start event` and `end event` around the synchronous portion of the * function execution, and will produce a `asyncStart event` and `asyncEnd event` around the callback execution. It may also produce an `error event` if the given function throws an error or @@ -540,13 +545,32 @@ declare module "diagnostics_channel" { * @param args Optional arguments to pass to the function * @return The return value of the given function */ - traceCallback any>( - fn: Fn, + traceCallback( + fn: (this: ThisArg, ...args: Args) => Result, position?: number, context?: ContextType, - thisArg?: any, - ...args: Parameters - ): void; + thisArg?: ThisArg, + ...args: Args + ): Result; + /** + * `true` if any of the individual channels has a subscriber, `false` if not. + * + * This is a helper method available on a {@link TracingChannel} instance to check + * if any of the [TracingChannel Channels](https://nodejs.org/api/diagnostics_channel.html#tracingchannel-channels) have subscribers. + * A `true` is returned if any of them have at least one subscriber, a `false` is returned otherwise. + * + * ```js + * const diagnostics_channel = require('node:diagnostics_channel'); + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * if (channels.hasSubscribers) { + * // Do something + * } + * ``` + * @since v22.0.0, v20.13.0 + */ + readonly hasSubscribers: boolean; } } declare module "node:diagnostics_channel" { diff --git a/node_modules/@types/node/dns.d.ts b/node_modules/@types/node/dns.d.ts index af10fd92c..c32003fcc 100644 --- a/node_modules/@types/node/dns.d.ts +++ b/node_modules/@types/node/dns.d.ts @@ -250,6 +250,9 @@ declare module "dns" { contactemail?: string | undefined; contactphone?: string | undefined; } + export interface AnyCaaRecord extends CaaRecord { + type: "CAA"; + } export interface MxRecord { priority: number; exchange: string; @@ -289,6 +292,15 @@ declare module "dns" { export interface AnySrvRecord extends SrvRecord { type: "SRV"; } + export interface TlsaRecord { + certUsage: number; + selector: number; + match: number; + data: ArrayBuffer; + } + export interface AnyTlsaRecord extends TlsaRecord { + type: "TLSA"; + } export interface AnyTxtRecord { type: "TXT"; entries: string[]; @@ -308,6 +320,7 @@ declare module "dns" { export type AnyRecord = | AnyARecord | AnyAaaaRecord + | AnyCaaRecord | AnyCnameRecord | AnyMxRecord | AnyNaptrRecord @@ -315,6 +328,7 @@ declare module "dns" { | AnyPtrRecord | AnySoaRecord | AnySrvRecord + | AnyTlsaRecord | AnyTxtRecord; /** * Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array @@ -335,12 +349,7 @@ declare module "dns" { ): void; export function resolve( hostname: string, - rrtype: "A", - callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, - ): void; - export function resolve( - hostname: string, - rrtype: "AAAA", + rrtype: "A" | "AAAA" | "CNAME" | "NS" | "PTR", callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, ): void; export function resolve( @@ -350,8 +359,8 @@ declare module "dns" { ): void; export function resolve( hostname: string, - rrtype: "CNAME", - callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + rrtype: "CAA", + callback: (err: NodeJS.ErrnoException | null, address: CaaRecord[]) => void, ): void; export function resolve( hostname: string, @@ -363,16 +372,6 @@ declare module "dns" { rrtype: "NAPTR", callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void, ): void; - export function resolve( - hostname: string, - rrtype: "NS", - callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, - ): void; - export function resolve( - hostname: string, - rrtype: "PTR", - callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, - ): void; export function resolve( hostname: string, rrtype: "SOA", @@ -383,6 +382,11 @@ declare module "dns" { rrtype: "SRV", callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void, ): void; + export function resolve( + hostname: string, + rrtype: "TLSA", + callback: (err: NodeJS.ErrnoException | null, addresses: TlsaRecord[]) => void, + ): void; export function resolve( hostname: string, rrtype: "TXT", @@ -393,21 +397,42 @@ declare module "dns" { rrtype: string, callback: ( err: NodeJS.ErrnoException | null, - addresses: string[] | MxRecord[] | NaptrRecord[] | SoaRecord | SrvRecord[] | string[][] | AnyRecord[], + addresses: + | string[] + | CaaRecord[] + | MxRecord[] + | NaptrRecord[] + | SoaRecord + | SrvRecord[] + | TlsaRecord[] + | string[][] + | AnyRecord[], ) => void, ): void; export namespace resolve { function __promisify__(hostname: string, rrtype?: "A" | "AAAA" | "CNAME" | "NS" | "PTR"): Promise; function __promisify__(hostname: string, rrtype: "ANY"): Promise; + function __promisify__(hostname: string, rrtype: "CAA"): Promise; function __promisify__(hostname: string, rrtype: "MX"): Promise; function __promisify__(hostname: string, rrtype: "NAPTR"): Promise; function __promisify__(hostname: string, rrtype: "SOA"): Promise; function __promisify__(hostname: string, rrtype: "SRV"): Promise; + function __promisify__(hostname: string, rrtype: "TLSA"): Promise; function __promisify__(hostname: string, rrtype: "TXT"): Promise; function __promisify__( hostname: string, rrtype: string, - ): Promise; + ): Promise< + | string[] + | CaaRecord[] + | MxRecord[] + | NaptrRecord[] + | SoaRecord + | SrvRecord[] + | TlsaRecord[] + | string[][] + | AnyRecord[] + >; } /** * Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the `hostname`. The `addresses` argument passed to the `callback` function @@ -609,6 +634,33 @@ declare module "dns" { export namespace resolveSrv { function __promisify__(hostname: string): Promise; } + /** + * Uses the DNS protocol to resolve certificate associations (`TLSA` records) for + * the `hostname`. The `records` argument passed to the `callback` function is an + * array of objects with these properties: + * + * * `certUsage` + * * `selector` + * * `match` + * * `data` + * + * ```js + * { + * certUsage: 3, + * selector: 1, + * match: 1, + * data: [ArrayBuffer] + * } + * ``` + * @since v22.15.0 + */ + export function resolveTlsa( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: TlsaRecord[]) => void, + ): void; + export namespace resolveTlsa { + function __promisify__(hostname: string): Promise; + } /** * Uses the DNS protocol to resolve text queries (`TXT` records) for the `hostname`. The `records` argument passed to the `callback` function is a * two-dimensional array of the text records available for `hostname` (e.g.`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of @@ -838,6 +890,7 @@ declare module "dns" { resolvePtr: typeof resolvePtr; resolveSoa: typeof resolveSoa; resolveSrv: typeof resolveSrv; + resolveTlsa: typeof resolveTlsa; resolveTxt: typeof resolveTxt; reverse: typeof reverse; /** diff --git a/node_modules/@types/node/dns/promises.d.ts b/node_modules/@types/node/dns/promises.d.ts index 2b5dff02a..a7ba9bb25 100644 --- a/node_modules/@types/node/dns/promises.d.ts +++ b/node_modules/@types/node/dns/promises.d.ts @@ -20,6 +20,7 @@ declare module "dns/promises" { ResolveWithTtlOptions, SoaRecord, SrvRecord, + TlsaRecord, } from "node:dns"; /** * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6), @@ -126,22 +127,26 @@ declare module "dns/promises" { * @param [rrtype='A'] Resource record type. */ function resolve(hostname: string): Promise; - function resolve(hostname: string, rrtype: "A"): Promise; - function resolve(hostname: string, rrtype: "AAAA"): Promise; + function resolve(hostname: string, rrtype: "A" | "AAAA" | "CNAME" | "NS" | "PTR"): Promise; function resolve(hostname: string, rrtype: "ANY"): Promise; function resolve(hostname: string, rrtype: "CAA"): Promise; - function resolve(hostname: string, rrtype: "CNAME"): Promise; function resolve(hostname: string, rrtype: "MX"): Promise; function resolve(hostname: string, rrtype: "NAPTR"): Promise; - function resolve(hostname: string, rrtype: "NS"): Promise; - function resolve(hostname: string, rrtype: "PTR"): Promise; function resolve(hostname: string, rrtype: "SOA"): Promise; function resolve(hostname: string, rrtype: "SRV"): Promise; + function resolve(hostname: string, rrtype: "TLSA"): Promise; function resolve(hostname: string, rrtype: "TXT"): Promise; - function resolve( - hostname: string, - rrtype: string, - ): Promise; + function resolve(hostname: string, rrtype: string): Promise< + | string[] + | CaaRecord[] + | MxRecord[] + | NaptrRecord[] + | SoaRecord + | SrvRecord[] + | TlsaRecord[] + | string[][] + | AnyRecord[] + >; /** * Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the `hostname`. On success, the `Promise` is resolved with an array of IPv4 * addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). @@ -292,6 +297,27 @@ declare module "dns/promises" { * @since v10.6.0 */ function resolveSrv(hostname: string): Promise; + /** + * Uses the DNS protocol to resolve certificate associations (`TLSA` records) for + * the `hostname`. On success, the `Promise` is resolved with an array of objectsAdd commentMore actions + * with these properties: + * + * * `certUsage` + * * `selector` + * * `match` + * * `data` + * + * ```js + * { + * certUsage: 3, + * selector: 1, + * match: 1, + * data: [ArrayBuffer] + * } + * ``` + * @since v22.15.0 + */ + function resolveTlsa(hostname: string): Promise; /** * Uses the DNS protocol to resolve text queries (`TXT` records) for the `hostname`. On success, the `Promise` is resolved with a two-dimensional array * of the text records available for `hostname` (e.g.`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of @@ -450,6 +476,7 @@ declare module "dns/promises" { resolvePtr: typeof resolvePtr; resolveSoa: typeof resolveSoa; resolveSrv: typeof resolveSrv; + resolveTlsa: typeof resolveTlsa; resolveTxt: typeof resolveTxt; reverse: typeof reverse; /** diff --git a/node_modules/@types/node/dom-events.d.ts b/node_modules/@types/node/dom-events.d.ts index f47f71d63..cd6acde28 100644 --- a/node_modules/@types/node/dom-events.d.ts +++ b/node_modules/@types/node/dom-events.d.ts @@ -1,77 +1,50 @@ -export {}; // Don't export anything! +// Make this a module +export {}; -//// DOM-like Events -// NB: The Event / EventTarget / EventListener implementations below were copied -// from lib.dom.d.ts, then edited to reflect Node's documentation at -// https://nodejs.org/api/events.html#class-eventtarget. -// Please read that link to understand important implementation differences. +// 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. -// This conditional type will be the existing global Event in a browser, or -// the copy below in a Node environment. -type __Event = typeof globalThis extends { onmessage: any; Event: any } ? {} - : { - /** This is not used in Node.js and is provided purely for completeness. */ - readonly bubbles: boolean; - /** Alias for event.stopPropagation(). This is not used in Node.js and is provided purely for completeness. */ - cancelBubble: () => void; - /** True if the event was created with the cancelable option */ - readonly cancelable: boolean; - /** This is not used in Node.js and is provided purely for completeness. */ - readonly composed: boolean; - /** Returns an array containing the current EventTarget as the only entry or empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness. */ - composedPath(): [EventTarget?]; - /** Alias for event.target. */ - readonly currentTarget: EventTarget | null; - /** Is true if cancelable is true and event.preventDefault() has been called. */ - readonly defaultPrevented: boolean; - /** This is not used in Node.js and is provided purely for completeness. */ - readonly eventPhase: 0 | 2; - /** The `AbortSignal` "abort" event is emitted with `isTrusted` set to `true`. The value is `false` in all other cases. */ - readonly isTrusted: boolean; - /** Sets the `defaultPrevented` property to `true` if `cancelable` is `true`. */ - preventDefault(): void; - /** This is not used in Node.js and is provided purely for completeness. */ - returnValue: boolean; - /** Alias for event.target. */ - readonly srcElement: EventTarget | null; - /** Stops the invocation of event listeners after the current one completes. */ - stopImmediatePropagation(): void; - /** This is not used in Node.js and is provided purely for completeness. */ - stopPropagation(): void; - /** The `EventTarget` dispatching the event */ - readonly target: EventTarget | null; - /** The millisecond timestamp when the Event object was created. */ - readonly timeStamp: number; - /** Returns the type of event, e.g. "click", "hashchange", or "submit". */ - readonly type: string; - }; +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; + readonly srcElement: EventTarget | null; + stopImmediatePropagation(): void; + stopPropagation(): void; + readonly target: EventTarget | null; + readonly timeStamp: number; + readonly type: string; +} -// See comment above explaining conditional type -type __EventTarget = typeof globalThis extends { onmessage: any; EventTarget: any } ? {} - : { - /** - * Adds a new handler for the `type` event. Any given `listener` is added only once per `type` and per `capture` option value. - * - * If the `once` option is true, the `listener` is removed after the next time a `type` event is dispatched. - * - * The `capture` option is not used by Node.js in any functional way other than tracking registered event listeners per the `EventTarget` specification. - * Specifically, the `capture` option is used as part of the key when registering a `listener`. - * Any individual `listener` may be added once with `capture = false`, and once with `capture = true`. - */ - addEventListener( - type: string, - listener: EventListener | EventListenerObject, - options?: AddEventListenerOptions | boolean, - ): void; - /** Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */ - dispatchEvent(event: Event): boolean; - /** Removes the event listener in target's event listener list with the same type, callback, and options. */ - removeEventListener( - type: string, - listener: EventListener | EventListenerObject, - options?: EventListenerOptions | boolean, - ): void; - }; +type __CustomEvent = typeof globalThis extends { onmessage: any } ? {} : CustomEvent; +interface CustomEvent extends Event { + readonly detail: T; +} + +type __EventTarget = typeof globalThis extends { onmessage: any } ? {} : EventTarget; +interface EventTarget { + addEventListener( + type: string, + listener: EventListener | EventListenerObject, + options?: AddEventListenerOptions | boolean, + ): void; + dispatchEvent(event: Event): boolean; + removeEventListener( + type: string, + listener: EventListener | EventListenerObject, + options?: EventListenerOptions | boolean, + ): void; +} interface EventInit { bubbles?: boolean; @@ -79,17 +52,17 @@ interface EventInit { composed?: boolean; } +interface CustomEventInit extends EventInit { + detail?: T; +} + interface EventListenerOptions { - /** Not directly used by Node.js. Added for API completeness. Default: `false`. */ capture?: boolean; } interface AddEventListenerOptions extends EventListenerOptions { - /** When `true`, the listener is automatically removed when it is first invoked. Default: `false`. */ once?: boolean; - /** When `true`, serves as a hint that the listener will not call the `Event` object's `preventDefault()` method. Default: false. */ passive?: boolean; - /** The listener will be removed when the given AbortSignal object's `abort()` method is called. */ signal?: AbortSignal; } @@ -101,24 +74,26 @@ interface EventListenerObject { handleEvent(object: Event): void; } -import {} from "events"; // Make this an ambient declaration +// Merge conditional interfaces into global scope, and conditionally declare global constructors. declare global { - /** An event which takes place in the DOM. */ interface Event extends __Event {} var Event: typeof globalThis extends { onmessage: any; Event: infer T } ? T : { - prototype: __Event; - new(type: string, eventInitDict?: EventInit): __Event; + prototype: Event; + new(type: string, eventInitDict?: EventInit): Event; + }; + + interface CustomEvent extends __CustomEvent {} + var CustomEvent: typeof globalThis extends { onmessage: any; CustomEvent: infer T } ? T + : { + prototype: CustomEvent; + new(type: string, eventInitDict?: CustomEventInit): CustomEvent; }; - /** - * EventTarget is a DOM interface implemented by objects that can - * receive events and may have listeners for them. - */ interface EventTarget extends __EventTarget {} var EventTarget: typeof globalThis extends { onmessage: any; EventTarget: infer T } ? T : { - prototype: __EventTarget; - new(): __EventTarget; + prototype: EventTarget; + new(): EventTarget; }; } diff --git a/node_modules/@types/node/events.d.ts b/node_modules/@types/node/events.d.ts index 63b943363..191227375 100644 --- a/node_modules/@types/node/events.d.ts +++ b/node_modules/@types/node/events.d.ts @@ -431,7 +431,6 @@ declare module "events" { * } * ``` * @since v20.5.0 - * @experimental * @return Disposable that removes the `abort` listener. */ static addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable; @@ -768,7 +767,7 @@ declare module "events" { setMaxListeners(n: number): this; /** * Returns the current max listener value for the `EventEmitter` which is either - * set by `emitter.setMaxListeners(n)` or defaults to {@link defaultMaxListeners}. + * set by `emitter.setMaxListeners(n)` or defaults to {@link EventEmitter.defaultMaxListeners}. * @since v1.0.0 */ getMaxListeners(): number; diff --git a/node_modules/@types/node/fs.d.ts b/node_modules/@types/node/fs.d.ts index cffa62d14..ca3b0502c 100644 --- a/node_modules/@types/node/fs.d.ts +++ b/node_modules/@types/node/fs.d.ts @@ -198,7 +198,7 @@ declare module "fs" { * the `withFileTypes` option set to `true`, the resulting array is filled with `fs.Dirent` objects, rather than strings or `Buffer` s. * @since v10.10.0 */ - export class Dirent { + export class Dirent { /** * Returns `true` if the `fs.Dirent` object describes a regular file. * @since v10.10.0 @@ -241,10 +241,10 @@ declare module "fs" { * value is determined by the `options.encoding` passed to {@link readdir} or {@link readdirSync}. * @since v10.10.0 */ - name: string; + name: Name; /** - * The base path that this `fs.Dirent` object refers to. - * @since v20.12.0 + * The path to the parent directory of the file this `fs.Dirent` object refers to. + * @since v20.12.0, v18.20.0 */ parentPath: string; /** @@ -328,6 +328,19 @@ declare module "fs" { * @since v12.12.0 */ readSync(): Dirent | null; + /** + * Calls `dir.close()` and returns a promise that fulfills when the + * dir is closed. + * @since v22.17.0 + * @experimental + */ + [Symbol.asyncDispose](): Promise; + /** + * Calls `dir.closeSync()` and returns `undefined`. + * @since v22.17.0 + * @experimental + */ + [Symbol.dispose](): void; } /** * Class: fs.StatWatcher @@ -438,57 +451,47 @@ declare module "fs" { * 2. close * 3. ready */ - addListener(event: "close", listener: () => void): this; - addListener(event: "data", listener: (chunk: Buffer | string) => void): this; - addListener(event: "end", listener: () => void): this; - addListener(event: "error", listener: (err: Error) => void): this; - addListener(event: "open", listener: (fd: number) => void): this; - addListener(event: "pause", listener: () => void): this; - addListener(event: "readable", listener: () => void): this; - addListener(event: "ready", listener: () => void): this; - addListener(event: "resume", listener: () => void): this; - addListener(event: string | symbol, listener: (...args: any[]) => void): this; - on(event: "close", listener: () => void): this; - on(event: "data", listener: (chunk: Buffer | string) => void): this; - on(event: "end", listener: () => void): this; - on(event: "error", listener: (err: Error) => void): this; - on(event: "open", listener: (fd: number) => void): this; - on(event: "pause", listener: () => void): this; - on(event: "readable", listener: () => void): this; - on(event: "ready", listener: () => void): this; - on(event: "resume", listener: () => void): this; - on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: "close", listener: () => void): this; - once(event: "data", listener: (chunk: Buffer | string) => void): this; - once(event: "end", listener: () => void): this; - once(event: "error", listener: (err: Error) => void): this; - once(event: "open", listener: (fd: number) => void): this; - once(event: "pause", listener: () => void): this; - once(event: "readable", listener: () => void): this; - once(event: "ready", listener: () => void): this; - once(event: "resume", listener: () => void): this; - once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: "close", listener: () => void): this; - prependListener(event: "data", listener: (chunk: Buffer | string) => void): this; - prependListener(event: "end", listener: () => void): this; - prependListener(event: "error", listener: (err: Error) => void): this; - prependListener(event: "open", listener: (fd: number) => void): this; - prependListener(event: "pause", listener: () => void): this; - prependListener(event: "readable", listener: () => void): this; - prependListener(event: "ready", listener: () => void): this; - prependListener(event: "resume", listener: () => void): this; - prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: "close", listener: () => void): this; - prependOnceListener(event: "data", listener: (chunk: Buffer | string) => void): this; - prependOnceListener(event: "end", listener: () => void): this; - prependOnceListener(event: "error", listener: (err: Error) => void): this; - prependOnceListener(event: "open", listener: (fd: number) => void): this; - prependOnceListener(event: "pause", listener: () => void): this; - prependOnceListener(event: "readable", listener: () => void): this; - prependOnceListener(event: "ready", listener: () => void): this; - prependOnceListener(event: "resume", listener: () => void): this; - prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + addListener(event: K, listener: ReadStreamEvents[K]): this; + on(event: K, listener: ReadStreamEvents[K]): this; + once(event: K, listener: ReadStreamEvents[K]): this; + prependListener(event: K, listener: ReadStreamEvents[K]): this; + prependOnceListener(event: K, listener: ReadStreamEvents[K]): this; } + + /** + * The Keys are events of the ReadStream and the values are the functions that are called when the event is emitted. + */ + type ReadStreamEvents = { + close: () => void; + data: (chunk: Buffer | string) => void; + end: () => void; + error: (err: Error) => void; + open: (fd: number) => void; + pause: () => void; + readable: () => void; + ready: () => void; + resume: () => void; + } & CustomEvents; + + /** + * string & {} allows to allow any kind of strings for the event + * but still allows to have auto completion for the normal events. + */ + type CustomEvents = { [Key in string & {} | symbol]: (...args: any[]) => void }; + + /** + * The Keys are events of the WriteStream and the values are the functions that are called when the event is emitted. + */ + type WriteStreamEvents = { + close: () => void; + drain: () => void; + error: (err: Error) => void; + finish: () => void; + open: (fd: number) => void; + pipe: (src: stream.Readable) => void; + ready: () => void; + unpipe: (src: stream.Readable) => void; + } & CustomEvents; /** * * Extends `stream.Writable` * @@ -527,51 +530,11 @@ declare module "fs" { * 2. close * 3. ready */ - addListener(event: "close", listener: () => void): this; - addListener(event: "drain", listener: () => void): this; - addListener(event: "error", listener: (err: Error) => void): this; - addListener(event: "finish", listener: () => void): this; - addListener(event: "open", listener: (fd: number) => void): this; - addListener(event: "pipe", listener: (src: stream.Readable) => void): this; - addListener(event: "ready", listener: () => void): this; - addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; - addListener(event: string | symbol, listener: (...args: any[]) => void): this; - on(event: "close", listener: () => void): this; - on(event: "drain", listener: () => void): this; - on(event: "error", listener: (err: Error) => void): this; - on(event: "finish", listener: () => void): this; - on(event: "open", listener: (fd: number) => void): this; - on(event: "pipe", listener: (src: stream.Readable) => void): this; - on(event: "ready", listener: () => void): this; - on(event: "unpipe", listener: (src: stream.Readable) => void): this; - on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: "close", listener: () => void): this; - once(event: "drain", listener: () => void): this; - once(event: "error", listener: (err: Error) => void): this; - once(event: "finish", listener: () => void): this; - once(event: "open", listener: (fd: number) => void): this; - once(event: "pipe", listener: (src: stream.Readable) => void): this; - once(event: "ready", listener: () => void): this; - once(event: "unpipe", listener: (src: stream.Readable) => void): this; - once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: "close", listener: () => void): this; - prependListener(event: "drain", listener: () => void): this; - prependListener(event: "error", listener: (err: Error) => void): this; - prependListener(event: "finish", listener: () => void): this; - prependListener(event: "open", listener: (fd: number) => void): this; - prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; - prependListener(event: "ready", listener: () => void): this; - prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; - prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: "close", listener: () => void): this; - prependOnceListener(event: "drain", listener: () => void): this; - prependOnceListener(event: "error", listener: (err: Error) => void): this; - prependOnceListener(event: "finish", listener: () => void): this; - prependOnceListener(event: "open", listener: (fd: number) => void): this; - prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; - prependOnceListener(event: "ready", listener: () => void): this; - prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; - prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + addListener(event: K, listener: WriteStreamEvents[K]): this; + on(event: K, listener: WriteStreamEvents[K]): this; + once(event: K, listener: WriteStreamEvents[K]): this; + prependListener(event: K, listener: WriteStreamEvents[K]): this; + prependOnceListener(event: K, listener: WriteStreamEvents[K]): this; } /** * Asynchronously rename file at `oldPath` to the pathname provided @@ -631,7 +594,7 @@ declare module "fs" { * @since v0.8.6 * @param [len=0] */ - export function truncate(path: PathLike, len: number | undefined | null, callback: NoParamCallback): void; + export function truncate(path: PathLike, len: number | undefined, callback: NoParamCallback): void; /** * Asynchronous truncate(2) - Truncate a file to a specified length. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -643,7 +606,7 @@ declare module "fs" { * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param len If not specified, defaults to `0`. */ - function __promisify__(path: PathLike, len?: number | null): Promise; + function __promisify__(path: PathLike, len?: number): Promise; } /** * Truncates the file. Returns `undefined`. A file descriptor can also be @@ -654,7 +617,7 @@ declare module "fs" { * @since v0.8.6 * @param [len=0] */ - export function truncateSync(path: PathLike, len?: number | null): void; + export function truncateSync(path: PathLike, len?: number): void; /** * Truncates the file descriptor. No arguments other than a possible exception are * given to the completion callback. @@ -698,7 +661,7 @@ declare module "fs" { * @since v0.8.6 * @param [len=0] */ - export function ftruncate(fd: number, len: number | undefined | null, callback: NoParamCallback): void; + export function ftruncate(fd: number, len: number | undefined, callback: NoParamCallback): void; /** * Asynchronous ftruncate(2) - Truncate a file to a specified length. * @param fd A file descriptor. @@ -710,7 +673,7 @@ declare module "fs" { * @param fd A file descriptor. * @param len If not specified, defaults to `0`. */ - function __promisify__(fd: number, len?: number | null): Promise; + function __promisify__(fd: number, len?: number): Promise; } /** * Truncates the file descriptor. Returns `undefined`. @@ -720,7 +683,7 @@ declare module "fs" { * @since v0.8.6 * @param [len=0] */ - export function ftruncateSync(fd: number, len?: number | null): void; + export function ftruncateSync(fd: number, len?: number): void; /** * Asynchronously changes owner and group of a file. No arguments other than a * possible exception are given to the completion callback. @@ -2090,6 +2053,20 @@ declare module "fs" { }, callback: (err: NodeJS.ErrnoException | null, files: Dirent[]) => void, ): void; + /** + * Asynchronous readdir(3) - read a directory. + * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. + * @param options Must include `withFileTypes: true` and `encoding: 'buffer'`. + */ + export function readdir( + path: PathLike, + options: { + encoding: "buffer"; + withFileTypes: true; + recursive?: boolean | undefined; + }, + callback: (err: NodeJS.ErrnoException | null, files: Dirent[]) => void, + ): void; export namespace readdir { /** * Asynchronous readdir(3) - read a directory. @@ -2149,6 +2126,19 @@ declare module "fs" { recursive?: boolean | undefined; }, ): Promise; + /** + * Asynchronous readdir(3) - read a directory. + * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. + * @param options Must include `withFileTypes: true` and `encoding: 'buffer'`. + */ + function __promisify__( + path: PathLike, + options: { + encoding: "buffer"; + withFileTypes: true; + recursive?: boolean | undefined; + }, + ): Promise[]>; } /** * Reads the contents of the directory. @@ -2216,6 +2206,19 @@ declare module "fs" { recursive?: boolean | undefined; }, ): Dirent[]; + /** + * Synchronous readdir(3) - read a directory. + * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. + * @param options Must include `withFileTypes: true` and `encoding: 'buffer'`. + */ + export function readdirSync( + path: PathLike, + options: { + encoding: "buffer"; + withFileTypes: true; + recursive?: boolean | undefined; + }, + ): Dirent[]; /** * Closes the file descriptor. No arguments other than a possible exception are * given to the completion callback. @@ -2369,6 +2372,20 @@ declare module "fs" { * @since v0.1.96 */ export function fsyncSync(fd: number): void; + export interface WriteOptions { + /** + * @default 0 + */ + offset?: number | undefined; + /** + * @default `buffer.byteLength - offset` + */ + length?: number | undefined; + /** + * @default null + */ + position?: number | undefined | null; + } /** * Write `buffer` to the file specified by `fd`. * @@ -2437,6 +2454,20 @@ declare module "fs" { buffer: TBuffer, callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, ): void; + /** + * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. + * @param fd A file descriptor. + * @param options An object with the following properties: + * * `offset` The part of the buffer to be written. If not supplied, defaults to `0`. + * * `length` The number of bytes to write. If not supplied, defaults to `buffer.length - offset`. + * * `position` The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position. + */ + export function write( + fd: number, + buffer: TBuffer, + options: WriteOptions, + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, + ): void; /** * Asynchronously writes `string` to the file referenced by the supplied file descriptor. * @param fd A file descriptor. @@ -2491,6 +2522,22 @@ declare module "fs" { bytesWritten: number; buffer: TBuffer; }>; + /** + * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. + * @param fd A file descriptor. + * @param options An object with the following properties: + * * `offset` The part of the buffer to be written. If not supplied, defaults to `0`. + * * `length` The number of bytes to write. If not supplied, defaults to `buffer.length - offset`. + * * `position` The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position. + */ + function __promisify__( + fd: number, + buffer?: TBuffer, + options?: WriteOptions, + ): Promise<{ + bytesWritten: number; + buffer: TBuffer; + }>; /** * Asynchronously writes `string` to the file referenced by the supplied file descriptor. * @param fd A file descriptor. @@ -2594,6 +2641,17 @@ declare module "fs" { options: ReadAsyncOptions, callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void, ): void; + export function read( + fd: number, + buffer: TBuffer, + options: ReadSyncOptions, + callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void, + ): void; + export function read( + fd: number, + buffer: TBuffer, + callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void, + ): void; export function read( fd: number, callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: NodeJS.ArrayBufferView) => void, @@ -2611,7 +2669,7 @@ declare module "fs" { buffer: TBuffer, offset: number, length: number, - position: number | null, + position: ReadPosition | null, ): Promise<{ bytesRead: number; buffer: TBuffer; @@ -2723,7 +2781,7 @@ declare module "fs" { } & Abortable) | undefined | null, - callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void, + callback: (err: NodeJS.ErrnoException | null, data: NonSharedBuffer) => void, ): void; /** * Asynchronously reads the entire contents of a file. @@ -2758,7 +2816,7 @@ declare module "fs" { | BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, data: string | Buffer) => void, + callback: (err: NodeJS.ErrnoException | null, data: string | NonSharedBuffer) => void, ): void; /** * Asynchronously reads the entire contents of a file. @@ -2767,7 +2825,7 @@ declare module "fs" { */ export function readFile( path: PathOrFileDescriptor, - callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void, + callback: (err: NodeJS.ErrnoException | null, data: NonSharedBuffer) => void, ): void; export namespace readFile { /** @@ -2783,7 +2841,7 @@ declare module "fs" { encoding?: null | undefined; flag?: string | undefined; } | null, - ): Promise; + ): Promise; /** * Asynchronously reads the entire contents of a file. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -2817,7 +2875,7 @@ declare module "fs" { }) | BufferEncoding | null, - ): Promise; + ): Promise; } /** * Returns the contents of the `path`. @@ -2849,7 +2907,7 @@ declare module "fs" { encoding?: null | undefined; flag?: string | undefined; } | null, - ): Buffer; + ): NonSharedBuffer; /** * Synchronously reads the entire contents of a file. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -2881,7 +2939,7 @@ declare module "fs" { }) | BufferEncoding | null, - ): string | Buffer; + ): string | NonSharedBuffer; export type WriteFileOptions = | ( & ObjectEncodingOptions @@ -3845,9 +3903,6 @@ declare module "fs" { flush?: boolean | undefined; } /** - * Unlike the 16 KiB default `highWaterMark` for a `stream.Readable`, the stream - * returned by this method has a default `highWaterMark` of 64 KiB. - * * `options` can include `start` and `end` values to read a range of bytes from * the file instead of the entire file. Both `start` and `end` are inclusive and * start counting at 0, allowed values are in the @@ -4065,7 +4120,7 @@ declare module "fs" { export function writev( fd: number, buffers: readonly NodeJS.ArrayBufferView[], - position: number, + position: number | null, cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void, ): void; export interface WriteVResult { @@ -4110,7 +4165,7 @@ declare module "fs" { export function readv( fd: number, buffers: readonly NodeJS.ArrayBufferView[], - position: number, + position: number | null, cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void, ): void; export interface ReadVResult { @@ -4158,7 +4213,6 @@ declare module "fs" { * blob.stream(); * ``` * @since v19.8.0 - * @experimental */ export function openAsBlob(path: PathLike, options?: OpenAsBlobOptions): Promise; @@ -4314,38 +4368,53 @@ declare module "fs" { */ export function cpSync(source: string | URL, destination: string | URL, opts?: CopySyncOptions): void; - export interface GlobOptions { + interface _GlobOptions { /** * Current working directory. * @default process.cwd() */ - cwd?: string | undefined; - /** - * Function to filter out files/directories. Return true to exclude the item, false to include it. - */ - exclude?: ((fileName: string) => boolean) | undefined; + cwd?: string | URL | undefined; /** * `true` if the glob should return paths as `Dirent`s, `false` otherwise. * @default false * @since v22.2.0 */ withFileTypes?: boolean | undefined; + /** + * Function to filter out files/directories or a + * list of glob patterns to be excluded. If a function is provided, return + * `true` to exclude the item, `false` to include it. + * @default undefined + */ + exclude?: ((fileName: T) => boolean) | readonly string[] | undefined; } - export interface GlobOptionsWithFileTypes extends GlobOptions { + export interface GlobOptions extends _GlobOptions {} + export interface GlobOptionsWithFileTypes extends _GlobOptions { withFileTypes: true; } - export interface GlobOptionsWithoutFileTypes extends GlobOptions { + export interface GlobOptionsWithoutFileTypes extends _GlobOptions { withFileTypes?: false | undefined; } + /** * Retrieves the files matching the specified pattern. + * + * ```js + * import { glob } from 'node:fs'; + * + * glob('*.js', (err, matches) => { + * if (err) throw err; + * console.log(matches); + * }); + * ``` + * @since v22.0.0 */ export function glob( - pattern: string | string[], + pattern: string | readonly string[], callback: (err: NodeJS.ErrnoException | null, matches: string[]) => void, ): void; export function glob( - pattern: string | string[], + pattern: string | readonly string[], options: GlobOptionsWithFileTypes, callback: ( err: NodeJS.ErrnoException | null, @@ -4353,7 +4422,7 @@ declare module "fs" { ) => void, ): void; export function glob( - pattern: string | string[], + pattern: string | readonly string[], options: GlobOptionsWithoutFileTypes, callback: ( err: NodeJS.ErrnoException | null, @@ -4361,7 +4430,7 @@ declare module "fs" { ) => void, ): void; export function glob( - pattern: string | string[], + pattern: string | readonly string[], options: GlobOptions, callback: ( err: NodeJS.ErrnoException | null, @@ -4369,19 +4438,25 @@ declare module "fs" { ) => void, ): void; /** - * Retrieves the files matching the specified pattern. + * ```js + * import { globSync } from 'node:fs'; + * + * console.log(globSync('*.js')); + * ``` + * @since v22.0.0 + * @returns paths of files that match the pattern. */ - export function globSync(pattern: string | string[]): string[]; + export function globSync(pattern: string | readonly string[]): string[]; export function globSync( - pattern: string | string[], + pattern: string | readonly string[], options: GlobOptionsWithFileTypes, ): Dirent[]; export function globSync( - pattern: string | string[], + pattern: string | readonly string[], options: GlobOptionsWithoutFileTypes, ): string[]; export function globSync( - pattern: string | string[], + pattern: string | readonly string[], options: GlobOptions, ): Dirent[] | string[]; } diff --git a/node_modules/@types/node/fs/promises.d.ts b/node_modules/@types/node/fs/promises.d.ts index 79726bd4f..b8186e93e 100644 --- a/node_modules/@types/node/fs/promises.d.ts +++ b/node_modules/@types/node/fs/promises.d.ts @@ -29,6 +29,7 @@ declare module "fs/promises" { OpenDirOptions, OpenMode, PathLike, + ReadPosition, ReadStream, ReadVResult, RmDirOptions, @@ -69,9 +70,9 @@ declare module "fs/promises" { * @default `buffer.byteLength` */ length?: number | null; - position?: number | null; + position?: ReadPosition | null; } - interface CreateReadStreamOptions { + interface CreateReadStreamOptions extends Abortable { encoding?: BufferEncoding | null | undefined; autoClose?: boolean | undefined; emitClose?: boolean | undefined; @@ -88,11 +89,7 @@ declare module "fs/promises" { flush?: boolean | undefined; } interface ReadableWebStreamOptions { - /** - * Whether to open a normal or a `'bytes'` stream. - * @since v20.0.0 - */ - type?: "bytes" | undefined; + autoClose?: boolean | undefined; } // TODO: Add `EventEmitter` close interface FileHandle { @@ -112,7 +109,7 @@ declare module "fs/promises" { appendFile( data: string | Uint8Array, options?: - | (ObjectEncodingOptions & FlagAndOpenMode & { flush?: boolean | undefined }) + | (ObjectEncodingOptions & Abortable) | BufferEncoding | null, ): Promise; @@ -236,11 +233,16 @@ declare module "fs/promises" { buffer: T, offset?: number | null, length?: number | null, - position?: number | null, + position?: ReadPosition | null, + ): Promise>; + read( + buffer: T, + options?: FileReadOptions, ): Promise>; read(options?: FileReadOptions): Promise>; /** - * Returns a `ReadableStream` that may be used to read the files data. + * Returns a byte-oriented `ReadableStream` that may be used to read the file's + * contents. * * An error will be thrown if this method is called more than once or is called * after the `FileHandle` is closed or closing. @@ -261,7 +263,6 @@ declare module "fs/promises" { * While the `ReadableStream` will read the file to completion, it will not * close the `FileHandle` automatically. User code must still call the`fileHandle.close()` method. * @since v17.0.0 - * @experimental */ readableWebStream(options?: ReadableWebStreamOptions): ReadableStream; /** @@ -279,36 +280,26 @@ declare module "fs/promises" { * data will be a string. */ readFile( - options?: { - encoding?: null | undefined; - flag?: OpenMode | undefined; - } | null, + options?: + | ({ encoding?: null | undefined } & Abortable) + | null, ): Promise; /** * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically. * The `FileHandle` must have been opened for reading. - * @param options An object that may contain an optional flag. - * If a flag is not provided, it defaults to `'r'`. */ readFile( options: - | { - encoding: BufferEncoding; - flag?: OpenMode | undefined; - } + | ({ encoding: BufferEncoding } & Abortable) | BufferEncoding, ): Promise; /** * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically. * The `FileHandle` must have been opened for reading. - * @param options An object that may contain an optional flag. - * If a flag is not provided, it defaults to `'r'`. */ readFile( options?: - | (ObjectEncodingOptions & { - flag?: OpenMode | undefined; - }) + | (ObjectEncodingOptions & Abortable) | BufferEncoding | null, ): Promise; @@ -398,7 +389,7 @@ declare module "fs/promises" { writeFile( data: string | Uint8Array, options?: - | (ObjectEncodingOptions & FlagAndOpenMode & Abortable & { flush?: boolean | undefined }) + | (ObjectEncodingOptions & Abortable) | BufferEncoding | null, ): Promise; @@ -429,6 +420,13 @@ declare module "fs/promises" { bytesWritten: number; buffer: TBuffer; }>; + write( + buffer: TBuffer, + options?: { offset?: number; length?: number; position?: number }, + ): Promise<{ + bytesWritten: number; + buffer: TBuffer; + }>; write( data: string, position?: number | null, @@ -479,7 +477,8 @@ declare module "fs/promises" { */ close(): Promise; /** - * An alias for {@link FileHandle.close()}. + * Calls `filehandle.close()` and returns a promise that fulfills when the + * filehandle is closed. * @since v20.4.0 */ [Symbol.asyncDispose](): Promise; @@ -723,6 +722,19 @@ declare module "fs/promises" { recursive?: boolean | undefined; }, ): Promise; + /** + * Asynchronous readdir(3) - read a directory. + * @param path A path to a directory. If a URL is provided, it must use the `file:` protocol. + * @param options Must include `withFileTypes: true` and `encoding: 'buffer'`. + */ + function readdir( + path: PathLike, + options: { + encoding: "buffer"; + withFileTypes: true; + recursive?: boolean | undefined; + }, + ): Promise[]>; /** * Reads the contents of the symbolic link referred to by `path`. See the POSIX [`readlink(2)`](http://man7.org/linux/man-pages/man2/readlink.2.html) documentation for more detail. The promise is * fulfilled with the`linkString` upon success. @@ -1243,20 +1255,28 @@ declare module "fs/promises" { */ function cp(source: string | URL, destination: string | URL, opts?: CopyOptions): Promise; /** - * Retrieves the files matching the specified pattern. + * ```js + * import { glob } from 'node:fs/promises'; + * + * for await (const entry of glob('*.js')) + * console.log(entry); + * ``` + * @since v22.0.0 + * @returns An AsyncIterator that yields the paths of files + * that match the pattern. */ - function glob(pattern: string | string[]): NodeJS.AsyncIterator; + function glob(pattern: string | readonly string[]): NodeJS.AsyncIterator; function glob( - pattern: string | string[], - opt: GlobOptionsWithFileTypes, + pattern: string | readonly string[], + options: GlobOptionsWithFileTypes, ): NodeJS.AsyncIterator; function glob( - pattern: string | string[], - opt: GlobOptionsWithoutFileTypes, + pattern: string | readonly string[], + options: GlobOptionsWithoutFileTypes, ): NodeJS.AsyncIterator; function glob( - pattern: string | string[], - opt: GlobOptions, + pattern: string | readonly string[], + options: GlobOptions, ): NodeJS.AsyncIterator; } declare module "node:fs/promises" { diff --git a/node_modules/@types/node/globals.d.ts b/node_modules/@types/node/globals.d.ts index e223aed92..f9f22d7b7 100644 --- a/node_modules/@types/node/globals.d.ts +++ b/node_modules/@types/node/globals.d.ts @@ -18,43 +18,11 @@ type _EventSource = typeof globalThis extends { onmessage: any } ? {} : import(" // Conditional type definitions for webstorage interface, which conflicts with lib.dom otherwise. type _Storage = typeof globalThis extends { onabort: any } ? {} : { - /** - * Returns the number of key/value pairs. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/length) - */ readonly length: number; - /** - * Removes all key/value pairs, if there are any. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/clear) - */ clear(): void; - /** - * Returns the current value associated with the given key, or null if the given key does not exist. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/getItem) - */ getItem(key: string): string | null; - /** - * Returns the name of the nth key, or null if n is greater than or equal to the number of key/value pairs. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/key) - */ key(index: number): string | null; - /** - * Removes the key/value pair with the given key, if a key/value pair with the given key exists. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/removeItem) - */ removeItem(key: string): void; - /** - * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously. - * - * Throws a "QuotaExceededError" DOMException exception if the new value couldn't be set. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/setItem) - */ setItem(key: string, value: string): void; [key: string]: any; }; @@ -62,15 +30,8 @@ type _Storage = typeof globalThis extends { onabort: any } ? {} : { // #region DOMException type _DOMException = typeof globalThis extends { onmessage: any } ? {} : NodeDOMException; interface NodeDOMException extends Error { - /** - * @deprecated - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/code) - */ readonly code: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/message) */ readonly message: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/name) */ readonly name: string; readonly INDEX_SIZE_ERR: 1; readonly DOMSTRING_SIZE_ERR: 2; @@ -130,275 +91,104 @@ interface NodeDOMExceptionConstructor { // #endregion DOMException declare global { - // Declare "static" methods in Error - interface ErrorConstructor { - /** Create .stack property on a target object */ - captureStackTrace(targetObject: object, constructorOpt?: Function): void; - - /** - * Optional override for formatting stack traces - * - * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces - */ - prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined; - - stackTraceLimit: number; - } - - /*-----------------------------------------------* - * * - * GLOBAL * - * * - ------------------------------------------------*/ - - // For backwards compability - interface NodeRequire extends NodeJS.Require {} - interface RequireResolve extends NodeJS.RequireResolve {} - interface NodeModule extends NodeJS.Module {} - var global: typeof globalThis; var process: NodeJS.Process; var console: Console; - var __filename: string; - var __dirname: string; - - var require: NodeRequire; - var module: NodeModule; - - // Same as module.exports - var exports: any; - - interface GCFunction { - (options: { - execution?: "sync"; - flavor?: "regular" | "last-resort"; - type?: "major-snapshot" | "major" | "minor"; - filename?: string; - }): void; - (options: { - execution: "async"; - flavor?: "regular" | "last-resort"; - type?: "major-snapshot" | "major" | "minor"; - filename?: string; - }): Promise; - (options?: boolean): void; - } - - /** - * Only available if `--expose-gc` is passed to the process. - */ - var gc: undefined | GCFunction; - - // #region borrowed - // from https://github.com/microsoft/TypeScript/blob/38da7c600c83e7b31193a62495239a0fe478cb67/lib/lib.webworker.d.ts#L633 until moved to separate lib - /** A controller object that allows you to abort one or more DOM requests as and when desired. */ - interface AbortController { + interface ErrorConstructor { /** - * Returns the AbortSignal object associated with this object. + * Creates a `.stack` property on `targetObject`, which when accessed returns + * a string representing the location in the code at which + * `Error.captureStackTrace()` was called. + * + * ```js + * const myObject = {}; + * Error.captureStackTrace(myObject); + * myObject.stack; // Similar to `new Error().stack` + * ``` + * + * The first line of the trace will be prefixed with + * `${myObject.name}: ${myObject.message}`. + * + * The optional `constructorOpt` argument accepts a function. If given, all frames + * above `constructorOpt`, including `constructorOpt`, will be omitted from the + * generated stack trace. + * + * The `constructorOpt` argument is useful for hiding implementation + * details of error generation from the user. For instance: + * + * ```js + * function a() { + * b(); + * } + * + * function b() { + * c(); + * } + * + * function c() { + * // Create an error without stack trace to avoid calculating the stack trace twice. + * const { stackTraceLimit } = Error; + * Error.stackTraceLimit = 0; + * const error = new Error(); + * Error.stackTraceLimit = stackTraceLimit; + * + * // Capture the stack trace above function b + * Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace + * throw error; + * } + * + * a(); + * ``` */ - - readonly signal: AbortSignal; + captureStackTrace(targetObject: object, constructorOpt?: Function): void; /** - * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted. + * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces */ - abort(reason?: any): void; - } - - /** A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object. */ - interface AbortSignal extends EventTarget { + prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any; /** - * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise. + * The `Error.stackTraceLimit` property specifies the number of stack frames + * collected by a stack trace (whether generated by `new Error().stack` or + * `Error.captureStackTrace(obj)`). + * + * The default value is `10` but may be set to any valid JavaScript number. Changes + * will affect any stack trace captured _after_ the value has been changed. + * + * If set to a non-number value, or set to a negative number, stack traces will + * not capture any frames. */ - readonly aborted: boolean; - readonly reason: any; - onabort: null | ((this: AbortSignal, event: Event) => any); - throwIfAborted(): void; + stackTraceLimit: number; } - var AbortController: typeof globalThis extends { onmessage: any; AbortController: infer T } ? T - : { - prototype: AbortController; - new(): AbortController; - }; - - var AbortSignal: typeof globalThis extends { onmessage: any; AbortSignal: infer T } ? T - : { - prototype: AbortSignal; - new(): AbortSignal; - abort(reason?: any): AbortSignal; - timeout(milliseconds: number): AbortSignal; - any(signals: AbortSignal[]): AbortSignal; - }; - // #endregion borrowed - - // #region Storage - /** - * This Web Storage API interface provides access to a particular domain's session or local storage. It allows, for example, the addition, modification, or deletion of stored data items. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage) - */ - interface Storage extends _Storage {} - - // Conditional on `onabort` rather than `onmessage`, in order to exclude lib.webworker - var Storage: typeof globalThis extends { onabort: any; Storage: infer T } ? T - : { - prototype: Storage; - new(): Storage; - }; - /** - * A browser-compatible implementation of [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). - * Data is stored unencrypted in the file specified by the `--localstorage-file` CLI flag. - * Any modification of this data outside of the Web Storage API is not supported. - * Enable this API with the `--experimental-webstorage` CLI flag. - * @since v22.4.0 + * Enable this API with the `--expose-gc` CLI flag. */ - var localStorage: Storage; + var gc: NodeJS.GCFunction | undefined; - /** - * A browser-compatible implementation of [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage). - * Data is stored in memory, with a storage quota of 10 MB. - * Any modification of this data outside of the Web Storage API is not supported. - * Enable this API with the `--experimental-webstorage` CLI flag. - * @since v22.4.0 - */ - var sessionStorage: Storage; - // #endregion Storage - - /** - * @since v17.0.0 - * - * Creates a deep clone of an object. - */ - function structuredClone( - value: T, - transfer?: { transfer: ReadonlyArray }, - ): T; - - // #region DOMException - /** - * @since v17.0.0 - * An abnormal event (called an exception) which occurs as a result of calling a method or accessing a property of a web API. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException) - */ - interface DOMException extends _DOMException {} - - /** - * @since v17.0.0 - * - * The WHATWG `DOMException` class. See [DOMException](https://developer.mozilla.org/docs/Web/API/DOMException) for more details. - */ - var DOMException: typeof globalThis extends { onmessage: any; DOMException: infer T } ? T - : NodeDOMExceptionConstructor; - // #endregion DOMException - - /*----------------------------------------------* - * * - * GLOBAL INTERFACES * - * * - *-----------------------------------------------*/ namespace NodeJS { interface CallSite { - /** - * Value of "this" - */ - getThis(): unknown; - - /** - * Type of "this" as a string. - * This is the name of the function stored in the constructor field of - * "this", if available. Otherwise the object's [[Class]] internal - * property. - */ - getTypeName(): string | null; - - /** - * Current function - */ + getColumnNumber(): number | null; + getEnclosingColumnNumber(): number | null; + getEnclosingLineNumber(): number | null; + getEvalOrigin(): string | undefined; + getFileName(): string | null; getFunction(): Function | undefined; - - /** - * Name of the current function, typically its name property. - * If a name property is not available an attempt will be made to try - * to infer a name from the function's context. - */ getFunctionName(): string | null; - - /** - * Name of the property [of "this" or one of its prototypes] that holds - * the current function - */ - getMethodName(): string | null; - - /** - * Name of the script [if this function was defined in a script] - */ - getFileName(): string | undefined; - - /** - * Current line number [if this function was defined in a script] - */ getLineNumber(): number | null; - - /** - * Current column number [if this function was defined in a script] - */ - getColumnNumber(): number | null; - - /** - * A call site object representing the location where eval was called - * [if this function was created using a call to eval] - */ - getEvalOrigin(): string | undefined; - - /** - * Is this a toplevel invocation, that is, is "this" the global object? - */ - isToplevel(): boolean; - - /** - * Does this call take place in code defined by a call to eval? - */ + getMethodName(): string | null; + getPosition(): number; + getPromiseIndex(): number | null; + getScriptHash(): string; + getScriptNameOrSourceURL(): string | null; + getThis(): unknown; + getTypeName(): string | null; + isAsync(): boolean; + isConstructor(): boolean; isEval(): boolean; - - /** - * Is this call in native V8 code? - */ isNative(): boolean; - - /** - * Is this a constructor call? - */ - isConstructor(): boolean; - - /** - * is this an async call (i.e. await, Promise.all(), or Promise.any())? - */ - isAsync(): boolean; - - /** - * is this an async call to Promise.all()? - */ isPromiseAll(): boolean; - - /** - * returns the index of the promise element that was followed in - * Promise.all() or Promise.any() for async stack traces, or null - * if the CallSite is not an async - */ - getPromiseIndex(): number | null; - - getScriptNameOrSourceURL(): string; - getScriptHash(): string; - - getEnclosingColumnNumber(): number; - getEnclosingLineNumber(): number; - getPosition(): number; - - toString(): string; + isToplevel(): boolean; } interface ErrnoException extends Error { @@ -419,7 +209,7 @@ declare global { unpipe(destination?: WritableStream): this; unshift(chunk: string | Uint8Array, encoding?: BufferEncoding): void; wrap(oldStream: ReadableStream): this; - [Symbol.asyncIterator](): NodeJS.AsyncIterator; + [Symbol.asyncIterator](): AsyncIterableIterator; } interface WritableStream extends EventEmitter { @@ -438,49 +228,6 @@ declare global { unref(): this; } - interface Require { - (id: string): any; - resolve: RequireResolve; - cache: Dict; - /** - * @deprecated - */ - extensions: RequireExtensions; - main: Module | undefined; - } - - interface RequireResolve { - (id: string, options?: { paths?: string[] | undefined }): string; - paths(request: string): string[] | null; - } - - interface RequireExtensions extends Dict<(m: Module, filename: string) => any> { - ".js": (m: Module, filename: string) => any; - ".json": (m: Module, filename: string) => any; - ".node": (m: Module, filename: string) => any; - } - interface Module { - /** - * `true` if the module is running during the Node.js preload - */ - isPreloading: boolean; - exports: any; - require: Require; - id: string; - filename: string; - loaded: boolean; - /** @deprecated since v14.6.0 Please use `require.main` and `module.children` instead. */ - parent: Module | null | undefined; - children: Module[]; - /** - * @since v11.14.0 - * - * The directory name of the module. This is usually the same as the path.dirname() of the module.id. - */ - path: string; - paths: string[]; - } - interface Dict { [key: string]: T | undefined; } @@ -489,21 +236,79 @@ declare global { readonly [key: string]: T | undefined; } + interface GCFunction { + (minor?: boolean): void; + (options: NodeJS.GCOptions & { execution: "async" }): Promise; + (options: NodeJS.GCOptions): void; + } + + interface GCOptions { + execution?: "sync" | "async" | undefined; + flavor?: "regular" | "last-resort" | undefined; + type?: "major-snapshot" | "major" | "minor" | undefined; + filename?: string | undefined; + } + /** An iterable iterator returned by the Node.js API. */ // Default TReturn/TNext in v22 is `any`, for compatibility with the previously-used IterableIterator. - // TODO: In next major @types/node version, change default TReturn to undefined. interface Iterator extends IteratorObject { [Symbol.iterator](): NodeJS.Iterator; } /** An async iterable iterator returned by the Node.js API. */ // Default TReturn/TNext in v22 is `any`, for compatibility with the previously-used AsyncIterableIterator. - // TODO: In next major @types/node version, change default TReturn to undefined. interface AsyncIterator extends AsyncIteratorObject { [Symbol.asyncIterator](): NodeJS.AsyncIterator; } } + // Global DOM types + + interface DOMException extends _DOMException {} + var DOMException: typeof globalThis extends { onmessage: any; DOMException: infer T } ? T + : NodeDOMExceptionConstructor; + + // #region AbortController + interface AbortController { + readonly signal: AbortSignal; + abort(reason?: any): void; + } + var AbortController: typeof globalThis extends { onmessage: any; AbortController: infer T } ? T + : { + prototype: AbortController; + new(): AbortController; + }; + + interface AbortSignal extends EventTarget { + readonly aborted: boolean; + onabort: ((this: AbortSignal, ev: Event) => any) | null; + readonly reason: any; + throwIfAborted(): void; + } + 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; + }; + // #endregion AbortController + + // #region Storage + interface Storage extends _Storage {} + // Conditional on `onabort` rather than `onmessage`, in order to exclude lib.webworker + var Storage: typeof globalThis extends { onabort: any; Storage: infer T } ? T + : { + prototype: Storage; + new(): Storage; + }; + + var localStorage: Storage; + var sessionStorage: Storage; + // #endregion Storage + + // #region fetch interface RequestInit extends _RequestInit {} function fetch( @@ -542,9 +347,6 @@ declare global { : typeof import("undici-types").Headers; interface MessageEvent extends _MessageEvent {} - /** - * @since v15.0.0 - */ var MessageEvent: typeof globalThis extends { onmessage: any; MessageEvent: infer T; @@ -556,11 +358,7 @@ declare global { : typeof import("undici-types").WebSocket; interface EventSource extends _EventSource {} - /** - * Only available through the [--experimental-eventsource](https://nodejs.org/api/cli.html#--experimental-eventsource) flag. - * - * @since v22.3.0 - */ var EventSource: typeof globalThis extends { onmessage: any; EventSource: infer T } ? T : typeof import("undici-types").EventSource; + // #endregion fetch } diff --git a/node_modules/@types/node/http.d.ts b/node_modules/@types/node/http.d.ts index 1f4de014f..96e0442d2 100644 --- a/node_modules/@types/node/http.d.ts +++ b/node_modules/@types/node/http.d.ts @@ -48,6 +48,7 @@ declare module "http" { // incoming headers will never contain number interface IncomingHttpHeaders extends NodeJS.Dict { accept?: string | undefined; + "accept-encoding"?: string | undefined; "accept-language"?: string | undefined; "accept-patch"?: string | undefined; "accept-ranges"?: string | undefined; @@ -94,6 +95,10 @@ declare module "http" { range?: string | undefined; referer?: string | undefined; "retry-after"?: string | undefined; + "sec-fetch-site"?: string | undefined; + "sec-fetch-mode"?: string | undefined; + "sec-fetch-user"?: string | undefined; + "sec-fetch-dest"?: string | undefined; "sec-websocket-accept"?: string | undefined; "sec-websocket-extensions"?: string | undefined; "sec-websocket-key"?: string | undefined; @@ -141,6 +146,7 @@ declare module "http" { "content-range"?: string | undefined; "content-security-policy"?: string | undefined; "content-security-policy-report-only"?: string | undefined; + "content-type"?: string | undefined; cookie?: string | string[] | undefined; dav?: string | string[] | undefined; dnt?: string | undefined; @@ -161,7 +167,7 @@ declare module "http" { location?: string | undefined; "max-forwards"?: string | undefined; origin?: string | undefined; - prgama?: string | string[] | undefined; + pragma?: string | string[] | undefined; "proxy-authenticate"?: string | string[] | undefined; "proxy-authorization"?: string | undefined; "public-key-pins"?: string | undefined; @@ -206,7 +212,7 @@ declare module "http" { | undefined; defaultPort?: number | string | undefined; family?: number | undefined; - headers?: OutgoingHttpHeaders | undefined; + headers?: OutgoingHttpHeaders | readonly string[] | undefined; hints?: LookupOptions["hints"]; host?: string | null | undefined; hostname?: string | null | undefined; @@ -222,6 +228,7 @@ declare module "http" { path?: string | null | undefined; port?: number | string | null | undefined; protocol?: string | null | undefined; + setDefaultHeaders?: boolean | undefined; setHost?: boolean | undefined; signal?: AbortSignal | undefined; socketPath?: string | undefined; @@ -267,6 +274,13 @@ declare module "http" { * @default 30000 */ connectionsCheckingInterval?: number | undefined; + /** + * Sets the timeout value in milliseconds for receiving the complete HTTP headers from the client. + * See {@link Server.headersTimeout} for more information. + * @default 60000 + * @since 18.0.0 + */ + headersTimeout?: number | undefined; /** * Optionally overrides all `socket`s' `readableHighWaterMark` and `writableHighWaterMark`. * This affects `highWaterMark` property of both `IncomingMessage` and `ServerResponse`. @@ -294,6 +308,13 @@ declare module "http" { * @since v16.5.0 */ noDelay?: boolean | undefined; + /** + * If set to `true`, it forces the server to respond with a 400 (Bad Request) status code + * to any HTTP/1.1 request message that lacks a Host header (as mandated by the specification). + * @default true + * @since 20.0.0 + */ + requireHostHeader?: boolean | undefined; /** * If set to `true`, it enables keep-alive functionality on the socket immediately after a new incoming connection is received, * similarly on what is done in `socket.setKeepAlive([enable][, initialDelay])`. @@ -312,6 +333,12 @@ declare module "http" { * If the header's value is an array, the items will be joined using `; `. */ uniqueHeaders?: Array | undefined; + /** + * If set to `true`, an error is thrown when writing to an HTTP response which does not have a body. + * @default false + * @since v18.17.0, v20.2.0 + */ + rejectNonStandardBodyWrites?: boolean | undefined; } type RequestListener< Request extends typeof IncomingMessage = typeof IncomingMessage, @@ -340,8 +367,8 @@ declare module "http" { * @since v0.9.12 * @param [msecs=0 (no timeout)] */ - setTimeout(msecs?: number, callback?: () => void): this; - setTimeout(callback: () => void): this; + setTimeout(msecs?: number, callback?: (socket: Socket) => void): this; + setTimeout(callback: (socket: Socket) => void): this; /** * Limits maximum incoming headers count. If set to 0, no limit will be applied. * @since v0.7.0 @@ -884,7 +911,7 @@ declare module "http" { * the request body should be sent. * @since v10.0.0 */ - writeProcessing(): void; + writeProcessing(callback?: () => void): void; } interface InformationEvent { statusCode: number; @@ -1543,6 +1570,68 @@ declare module "http" { * @since v0.11.4 */ destroy(): void; + /** + * Produces a socket/stream to be used for HTTP requests. + * + * By default, this function is the same as `net.createConnection()`. However, + * custom agents may override this method in case greater flexibility is desired. + * + * A socket/stream can be supplied in one of two ways: by returning the + * socket/stream from this function, or by passing the socket/stream to `callback`. + * + * This method is guaranteed to return an instance of the `net.Socket` class, + * a subclass of `stream.Duplex`, unless the user specifies a socket + * type other than `net.Socket`. + * + * `callback` has a signature of `(err, stream)`. + * @since v0.11.4 + * @param options Options containing connection details. Check `createConnection` for the format of the options + * @param callback Callback function that receives the created socket + */ + createConnection( + options: ClientRequestArgs, + callback?: (err: Error | null, stream: stream.Duplex) => void, + ): stream.Duplex; + /** + * Called when `socket` is detached from a request and could be persisted by the`Agent`. Default behavior is to: + * + * ```js + * socket.setKeepAlive(true, this.keepAliveMsecs); + * socket.unref(); + * return true; + * ``` + * + * This method can be overridden by a particular `Agent` subclass. If this + * method returns a falsy value, the socket will be destroyed instead of persisting + * it for use with the next request. + * + * The `socket` argument can be an instance of `net.Socket`, a subclass of `stream.Duplex`. + * @since v8.1.0 + */ + keepSocketAlive(socket: stream.Duplex): void; + /** + * Called when `socket` is attached to `request` after being persisted because of + * the keep-alive options. Default behavior is to: + * + * ```js + * socket.ref(); + * ``` + * + * This method can be overridden by a particular `Agent` subclass. + * + * The `socket` argument can be an instance of `net.Socket`, a subclass of `stream.Duplex`. + * @since v8.1.0 + */ + reuseSocket(socket: stream.Duplex, request: ClientRequest): void; + /** + * Get a unique name for a set of request options, to determine whether a + * connection can be reused. For an HTTP agent, this returns`host:port:localAddress` or `host:port:localAddress:family`. For an HTTPS agent, + * the name includes the CA, cert, ciphers, and other HTTPS/TLS-specific options + * that determine socket reusability. + * @since v0.11.4 + * @param options A set of options providing information for name generation + */ + getName(options?: ClientRequestArgs): string; } const METHODS: string[]; const STATUS_CODES: { diff --git a/node_modules/@types/node/http2.d.ts b/node_modules/@types/node/http2.d.ts index 0838ae8b9..e60f0e1ca 100644 --- a/node_modules/@types/node/http2.d.ts +++ b/node_modules/@types/node/http2.d.ts @@ -965,7 +965,10 @@ declare module "http2" { * * `:path` \= `/` * @since v8.4.0 */ - request(headers?: OutgoingHttpHeaders, options?: ClientSessionRequestOptions): ClientHttp2Stream; + request( + headers?: OutgoingHttpHeaders | readonly string[], + options?: ClientSessionRequestOptions, + ): ClientHttp2Stream; addListener(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; addListener(event: "origin", listener: (origins: string[]) => void): this; addListener( @@ -1223,14 +1226,66 @@ declare module "http2" { } // Http2Server export interface SessionOptions { + /** + * Sets the maximum dynamic table size for deflating header fields. + * @default 4Kib + */ maxDeflateDynamicTableSize?: number | undefined; + /** + * Sets the maximum number of settings entries per `SETTINGS` frame. + * The minimum value allowed is `1`. + * @default 32 + */ + maxSettings?: number | undefined; + /** + * Sets the maximum memory that the `Http2Session` is permitted to use. + * The value is expressed in terms of number of megabytes, e.g. `1` equal 1 megabyte. + * The minimum value allowed is `1`. + * This is a credit based limit, existing `Http2Stream`s may cause this limit to be exceeded, + * but new `Http2Stream` instances will be rejected while this limit is exceeded. + * The current number of `Http2Stream` sessions, the current memory use of the header compression tables, + * current data queued to be sent, and unacknowledged `PING` and `SETTINGS` frames are all counted towards the current limit. + * @default 10 + */ maxSessionMemory?: number | undefined; + /** + * Sets the maximum number of header entries. + * This is similar to `server.maxHeadersCount` or `request.maxHeadersCount` in the `node:http` module. + * The minimum value is `1`. + * @default 128 + */ maxHeaderListPairs?: number | undefined; + /** + * Sets the maximum number of outstanding, unacknowledged pings. + * @default 10 + */ maxOutstandingPings?: number | undefined; + /** + * Sets the maximum allowed size for a serialized, compressed block of headers. + * Attempts to send headers that exceed this limit will result in + * a `'frameError'` event being emitted and the stream being closed and destroyed. + */ maxSendHeaderBlockLength?: number | undefined; + /** + * Strategy used for determining the amount of padding to use for `HEADERS` and `DATA` frames. + * @default http2.constants.PADDING_STRATEGY_NONE + */ paddingStrategy?: number | undefined; + /** + * Sets the maximum number of concurrent streams for the remote peer as if a `SETTINGS` frame had been received. + * Will be overridden if the remote peer sets its own value for `maxConcurrentStreams`. + * @default 100 + */ peerMaxConcurrentStreams?: number | undefined; + /** + * The initial settings to send to the remote peer upon connection. + */ settings?: Settings | undefined; + /** + * The array of integer values determines the settings types, + * which are included in the `CustomSettings`-property of the received remoteSettings. + * Please see the `CustomSettings`-property of the `Http2Settings` object for more information, on the allowed setting types. + */ remoteCustomSettings?: number[] | undefined; /** * Specifies a timeout in milliseconds that @@ -1239,11 +1294,35 @@ declare module "http2" { * @default 100000 */ unknownProtocolTimeout?: number | undefined; - selectPadding?(frameLen: number, maxFrameLen: number): number; + /** + * If `true`, it turns on strict leading + * and trailing whitespace validation for HTTP/2 header field names and values + * as per [RFC-9113](https://www.rfc-editor.org/rfc/rfc9113.html#section-8.2.1). + * @since v24.2.0 + * @default true + */ + strictFieldWhitespaceValidation?: boolean | undefined; } export interface ClientSessionOptions extends SessionOptions { + /** + * Sets the maximum number of reserved push streams the client will accept at any given time. + * Once the current number of currently reserved push streams exceeds reaches this limit, + * new push streams sent by the server will be automatically rejected. + * The minimum allowed value is 0. The maximum allowed value is 232-1. + * A negative value sets this option to the maximum allowed value. + * @default 200 + */ maxReservedRemoteStreams?: number | undefined; + /** + * An optional callback that receives the `URL` instance passed to `connect` and the `options` object, + * and returns any `Duplex` stream that is to be used as the connection for this session. + */ createConnection?: ((authority: url.URL, option: SessionOptions) => stream.Duplex) | undefined; + /** + * The protocol to connect with, if not set in the `authority`. + * Value may be either `'http:'` or `'https:'`. + * @default 'https:' + */ protocol?: "http:" | "https:" | undefined; } export interface ServerSessionOptions< @@ -1252,6 +1331,8 @@ declare module "http2" { Http2Request extends typeof Http2ServerRequest = typeof Http2ServerRequest, Http2Response extends typeof Http2ServerResponse> = typeof Http2ServerResponse, > extends SessionOptions { + streamResetBurst?: number | undefined; + streamResetRate?: number | undefined; Http1IncomingMessage?: Http1Request | undefined; Http1ServerResponse?: Http1Response | undefined; Http2ServerRequest?: Http2Request | undefined; diff --git a/node_modules/@types/node/https.d.ts b/node_modules/@types/node/https.d.ts index 7112b8d42..b74d9d291 100644 --- a/node_modules/@types/node/https.d.ts +++ b/node_modules/@types/node/https.d.ts @@ -16,12 +16,13 @@ declare module "https" { & http.RequestOptions & tls.SecureContextOptions & { - checkServerIdentity?: typeof tls.checkServerIdentity | undefined; + checkServerIdentity?: + | ((hostname: string, cert: tls.DetailedPeerCertificate) => Error | undefined) + | undefined; rejectUnauthorized?: boolean | undefined; // Defaults to true servername?: string | undefined; // SNI TLS Extension }; interface AgentOptions extends http.AgentOptions, tls.ConnectionOptions { - rejectUnauthorized?: boolean | undefined; maxCachedSessions?: number | undefined; } /** diff --git a/node_modules/@types/node/inspector.d.ts b/node_modules/@types/node/inspector.d.ts index 32d9ba4aa..ebcdb7a10 100644 --- a/node_modules/@types/node/inspector.d.ts +++ b/node_modules/@types/node/inspector.d.ts @@ -1720,6 +1720,38 @@ declare module 'inspector' { * Monotonically increasing time in seconds since an arbitrary point in the past. */ type MonotonicTime = number; + /** + * Information about the request initiator. + */ + interface Initiator { + /** + * Type of this initiator. + */ + type: string; + /** + * Initiator JavaScript stack trace, set for Script only. + * Requires the Debugger domain to be enabled. + */ + stack?: Runtime.StackTrace | undefined; + /** + * Initiator URL, set for Parser type or for Script type (when script is importing module) or for SignedExchange type. + */ + url?: string | undefined; + /** + * Initiator line number, set for Parser type or for Script type (when script is importing + * module) (0-based). + */ + lineNumber?: number | undefined; + /** + * Initiator column number, set for Parser type or for Script type (when script is importing + * module) (0-based). + */ + columnNumber?: number | undefined; + /** + * Set if another request triggered this request (e.g. preflight). + */ + requestId?: RequestId | undefined; + } /** * HTTP request data. */ @@ -1736,12 +1768,26 @@ declare module 'inspector' { status: number; statusText: string; headers: Headers; + mimeType: string; + charset: string; } /** * Request / response headers as keys / values of JSON object. */ interface Headers { } + interface StreamResourceContentParameterType { + /** + * Identifier of the request to stream. + */ + requestId: RequestId; + } + interface StreamResourceContentReturnType { + /** + * Data that has been buffered until streaming is enabled. + */ + bufferedData: never; + } interface RequestWillBeSentEventDataType { /** * Request identifier. @@ -1751,6 +1797,10 @@ declare module 'inspector' { * Request data. */ request: Request; + /** + * Request initiator. + */ + initiator: Initiator; /** * Timestamp. */ @@ -1806,12 +1856,59 @@ declare module 'inspector' { */ timestamp: MonotonicTime; } + interface DataReceivedEventDataType { + /** + * Request identifier. + */ + requestId: RequestId; + /** + * Timestamp. + */ + timestamp: MonotonicTime; + /** + * Data chunk length. + */ + dataLength: number; + /** + * Actual bytes received (might be less than dataLength for compressed encodings). + */ + encodedDataLength: number; + /** + * Data that was received. + * @experimental + */ + data?: never | undefined; + } } namespace NodeRuntime { interface NotifyWhenWaitingForDisconnectParameterType { enabled: boolean; } } + namespace Target { + type SessionID = string; + type TargetID = string; + interface TargetInfo { + targetId: TargetID; + type: string; + title: string; + url: string; + attached: boolean; + canAccessOpener: boolean; + } + interface SetAutoAttachParameterType { + autoAttach: boolean; + waitForDebuggerOnStart: boolean; + } + interface TargetCreatedEventDataType { + targetInfo: TargetInfo; + } + interface AttachedToTargetEventDataType { + sessionId: SessionID; + targetInfo: TargetInfo; + waitingForDebugger: boolean; + } + } /** * The `inspector.Session` is used for dispatching messages to the V8 inspector @@ -2188,6 +2285,17 @@ declare module 'inspector' { * Enables network tracking, network events will now be delivered to the client. */ post(method: 'Network.enable', callback?: (err: Error | null) => void): void; + /** + * Enables streaming of the response for the given requestId. + * If enabled, the dataReceived event contains the data that was received during streaming. + * @experimental + */ + post( + method: 'Network.streamResourceContent', + params?: Network.StreamResourceContentParameterType, + callback?: (err: Error | null, params: Network.StreamResourceContentReturnType) => void + ): void; + post(method: 'Network.streamResourceContent', callback?: (err: Error | null, params: Network.StreamResourceContentReturnType) => void): void; /** * Enable the NodeRuntime events except by `NodeRuntime.waitingForDisconnect`. */ @@ -2201,6 +2309,8 @@ declare module 'inspector' { */ post(method: 'NodeRuntime.notifyWhenWaitingForDisconnect', params?: NodeRuntime.NotifyWhenWaitingForDisconnectParameterType, callback?: (err: Error | null) => void): void; post(method: 'NodeRuntime.notifyWhenWaitingForDisconnect', callback?: (err: Error | null) => void): void; + post(method: 'Target.setAutoAttach', params?: Target.SetAutoAttachParameterType, callback?: (err: Error | null) => void): void; + post(method: 'Target.setAutoAttach', callback?: (err: Error | null) => void): void; addListener(event: string, listener: (...args: any[]) => void): this; /** @@ -2307,6 +2417,10 @@ declare module 'inspector' { addListener(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; addListener(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; addListener(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + addListener(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -2319,6 +2433,8 @@ declare module 'inspector' { * example, when inspector.waitingForDebugger is called */ addListener(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + addListener(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + addListener(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; emit(event: string | symbol, ...args: any[]): boolean; emit(event: 'inspectorNotification', message: InspectorNotification): boolean; emit(event: 'Runtime.executionContextCreated', message: InspectorNotification): boolean; @@ -2350,8 +2466,11 @@ declare module 'inspector' { emit(event: 'Network.responseReceived', message: InspectorNotification): boolean; emit(event: 'Network.loadingFailed', message: InspectorNotification): boolean; emit(event: 'Network.loadingFinished', message: InspectorNotification): boolean; + emit(event: 'Network.dataReceived', message: InspectorNotification): boolean; emit(event: 'NodeRuntime.waitingForDisconnect'): boolean; emit(event: 'NodeRuntime.waitingForDebugger'): boolean; + emit(event: 'Target.targetCreated', message: InspectorNotification): boolean; + emit(event: 'Target.attachedToTarget', message: InspectorNotification): boolean; on(event: string, listener: (...args: any[]) => void): this; /** * Emitted when any notification from the V8 Inspector is received. @@ -2457,6 +2576,10 @@ declare module 'inspector' { on(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; on(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; on(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + on(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -2469,6 +2592,8 @@ declare module 'inspector' { * example, when inspector.waitingForDebugger is called */ on(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + on(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + on(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; once(event: string, listener: (...args: any[]) => void): this; /** * Emitted when any notification from the V8 Inspector is received. @@ -2574,6 +2699,10 @@ declare module 'inspector' { once(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; once(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; once(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + once(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -2586,6 +2715,8 @@ declare module 'inspector' { * example, when inspector.waitingForDebugger is called */ once(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + once(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + once(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; /** * Emitted when any notification from the V8 Inspector is received. @@ -2691,6 +2822,10 @@ declare module 'inspector' { prependListener(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; prependListener(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; prependListener(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + prependListener(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -2703,6 +2838,8 @@ declare module 'inspector' { * example, when inspector.waitingForDebugger is called */ prependListener(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + prependListener(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + prependListener(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; /** * Emitted when any notification from the V8 Inspector is received. @@ -2808,6 +2945,10 @@ declare module 'inspector' { prependOnceListener(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; prependOnceListener(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; prependOnceListener(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + prependOnceListener(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -2820,6 +2961,8 @@ declare module 'inspector' { * example, when inspector.waitingForDebugger is called */ prependOnceListener(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + prependOnceListener(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + prependOnceListener(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; } /** @@ -2906,13 +3049,20 @@ declare module 'inspector' { // DevTools protocol event broadcast methods namespace Network { + /** + * This feature is only available with the `--experimental-network-inspection` flag enabled. + * + * Broadcasts the `Network.dataReceived` event to connected frontends, or buffers the data if + * `Network.streamResourceContent` command was not invoked for the given request yet. + * @since v22.17.0 + */ + function dataReceived(params: DataReceivedEventDataType): void; /** * This feature is only available with the `--experimental-network-inspection` flag enabled. * * Broadcasts the `Network.requestWillBeSent` event to connected frontends. This event indicates that * the application is about to send an HTTP request. * @since v22.6.0 - * @experimental */ function requestWillBeSent(params: RequestWillBeSentEventDataType): void; /** @@ -2921,7 +3071,6 @@ declare module 'inspector' { * Broadcasts the `Network.responseReceived` event to connected frontends. This event indicates that * HTTP response is available. * @since v22.6.0 - * @experimental */ function responseReceived(params: ResponseReceivedEventDataType): void; /** @@ -2930,7 +3079,6 @@ declare module 'inspector' { * Broadcasts the `Network.loadingFinished` event to connected frontends. This event indicates that * HTTP request has finished loading. * @since v22.6.0 - * @experimental */ function loadingFinished(params: LoadingFinishedEventDataType): void; /** @@ -2939,7 +3087,6 @@ declare module 'inspector' { * Broadcasts the `Network.loadingFailed` event to connected frontends. This event indicates that * HTTP request has failed to load. * @since v22.7.0 - * @experimental */ function loadingFailed(params: LoadingFailedEventDataType): void; } @@ -2978,6 +3125,7 @@ declare module 'inspector/promises' { NodeWorker, Network, NodeRuntime, + Target, } from 'inspector'; /** @@ -3302,6 +3450,12 @@ declare module 'inspector/promises' { * Enables network tracking, network events will now be delivered to the client. */ post(method: 'Network.enable'): Promise; + /** + * Enables streaming of the response for the given requestId. + * If enabled, the dataReceived event contains the data that was received during streaming. + * @experimental + */ + post(method: 'Network.streamResourceContent', params?: Network.StreamResourceContentParameterType): Promise; /** * Enable the NodeRuntime events except by `NodeRuntime.waitingForDisconnect`. */ @@ -3314,6 +3468,7 @@ declare module 'inspector/promises' { * Enable the `NodeRuntime.waitingForDisconnect`. */ post(method: 'NodeRuntime.notifyWhenWaitingForDisconnect', params?: NodeRuntime.NotifyWhenWaitingForDisconnectParameterType): Promise; + post(method: 'Target.setAutoAttach', params?: Target.SetAutoAttachParameterType): Promise; addListener(event: string, listener: (...args: any[]) => void): this; /** @@ -3420,6 +3575,10 @@ declare module 'inspector/promises' { addListener(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; addListener(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; addListener(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + addListener(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -3432,6 +3591,8 @@ declare module 'inspector/promises' { * example, when inspector.waitingForDebugger is called */ addListener(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + addListener(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + addListener(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; emit(event: string | symbol, ...args: any[]): boolean; emit(event: 'inspectorNotification', message: InspectorNotification): boolean; emit(event: 'Runtime.executionContextCreated', message: InspectorNotification): boolean; @@ -3463,8 +3624,11 @@ declare module 'inspector/promises' { emit(event: 'Network.responseReceived', message: InspectorNotification): boolean; emit(event: 'Network.loadingFailed', message: InspectorNotification): boolean; emit(event: 'Network.loadingFinished', message: InspectorNotification): boolean; + emit(event: 'Network.dataReceived', message: InspectorNotification): boolean; emit(event: 'NodeRuntime.waitingForDisconnect'): boolean; emit(event: 'NodeRuntime.waitingForDebugger'): boolean; + emit(event: 'Target.targetCreated', message: InspectorNotification): boolean; + emit(event: 'Target.attachedToTarget', message: InspectorNotification): boolean; on(event: string, listener: (...args: any[]) => void): this; /** * Emitted when any notification from the V8 Inspector is received. @@ -3570,6 +3734,10 @@ declare module 'inspector/promises' { on(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; on(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; on(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + on(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -3582,6 +3750,8 @@ declare module 'inspector/promises' { * example, when inspector.waitingForDebugger is called */ on(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + on(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + on(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; once(event: string, listener: (...args: any[]) => void): this; /** * Emitted when any notification from the V8 Inspector is received. @@ -3687,6 +3857,10 @@ declare module 'inspector/promises' { once(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; once(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; once(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + once(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -3699,6 +3873,8 @@ declare module 'inspector/promises' { * example, when inspector.waitingForDebugger is called */ once(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + once(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + once(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; /** * Emitted when any notification from the V8 Inspector is received. @@ -3804,6 +3980,10 @@ declare module 'inspector/promises' { prependListener(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; prependListener(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; prependListener(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + prependListener(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -3816,6 +3996,8 @@ declare module 'inspector/promises' { * example, when inspector.waitingForDebugger is called */ prependListener(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + prependListener(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + prependListener(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; /** * Emitted when any notification from the V8 Inspector is received. @@ -3921,6 +4103,10 @@ declare module 'inspector/promises' { prependOnceListener(event: 'Network.responseReceived', listener: (message: InspectorNotification) => void): this; prependOnceListener(event: 'Network.loadingFailed', listener: (message: InspectorNotification) => void): this; prependOnceListener(event: 'Network.loadingFinished', listener: (message: InspectorNotification) => void): this; + /** + * Fired when data chunk was received over the network. + */ + prependOnceListener(event: 'Network.dataReceived', listener: (message: InspectorNotification) => void): this; /** * This event is fired instead of `Runtime.executionContextDestroyed` when * enabled. @@ -3933,6 +4119,8 @@ declare module 'inspector/promises' { * example, when inspector.waitingForDebugger is called */ prependOnceListener(event: 'NodeRuntime.waitingForDebugger', listener: () => void): this; + prependOnceListener(event: 'Target.targetCreated', listener: (message: InspectorNotification) => void): this; + prependOnceListener(event: 'Target.attachedToTarget', listener: (message: InspectorNotification) => void): this; } export { @@ -3953,6 +4141,7 @@ declare module 'inspector/promises' { NodeWorker, Network, NodeRuntime, + Target, }; } diff --git a/node_modules/@types/node/module.d.ts b/node_modules/@types/node/module.d.ts index 4f386598f..ebd3abe5f 100644 --- a/node_modules/@types/node/module.d.ts +++ b/node_modules/@types/node/module.d.ts @@ -1,11 +1,325 @@ /** * @since v0.3.7 - * @experimental */ declare module "module" { import { URL } from "node:url"; - import { MessagePort } from "node:worker_threads"; + class Module { + constructor(id: string, parent?: Module); + } + interface Module extends NodeJS.Module {} + namespace Module { + export { Module }; + } namespace Module { + /** + * A list of the names of all modules provided by Node.js. Can be used to verify + * if a module is maintained by a third party or not. + * + * Note: the list doesn't contain prefix-only modules like `node:test`. + * @since v9.3.0, v8.10.0, v6.13.0 + */ + const builtinModules: readonly string[]; + /** + * @since v12.2.0 + * @param path Filename to be used to construct the require + * function. Must be a file URL object, file URL string, or absolute path + * string. + */ + function createRequire(path: string | URL): NodeJS.Require; + namespace constants { + /** + * The following constants are returned as the `status` field in the object returned by + * {@link enableCompileCache} to indicate the result of the attempt to enable the + * [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache). + * @since v22.8.0 + */ + namespace compileCacheStatus { + /** + * Node.js has enabled the compile cache successfully. The directory used to store the + * compile cache will be returned in the `directory` field in the + * returned object. + */ + const ENABLED: number; + /** + * The compile cache has already been enabled before, either by a previous call to + * {@link enableCompileCache}, or by the `NODE_COMPILE_CACHE=dir` + * environment variable. The directory used to store the + * compile cache will be returned in the `directory` field in the + * returned object. + */ + const ALREADY_ENABLED: number; + /** + * Node.js fails to enable the compile cache. This can be caused by the lack of + * permission to use the specified directory, or various kinds of file system errors. + * The detail of the failure will be returned in the `message` field in the + * returned object. + */ + const FAILED: number; + /** + * Node.js cannot enable the compile cache because the environment variable + * `NODE_DISABLE_COMPILE_CACHE=1` has been set. + */ + const DISABLED: number; + } + } + interface EnableCompileCacheResult { + /** + * One of the {@link constants.compileCacheStatus} + */ + status: number; + /** + * If Node.js cannot enable the compile cache, this contains + * the error message. Only set if `status` is `module.constants.compileCacheStatus.FAILED`. + */ + message?: string; + /** + * If the compile cache is enabled, this contains the directory + * where the compile cache is stored. Only set if `status` is + * `module.constants.compileCacheStatus.ENABLED` or + * `module.constants.compileCacheStatus.ALREADY_ENABLED`. + */ + directory?: string; + } + /** + * Enable [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache) + * in the current Node.js instance. + * + * If `cacheDir` is not specified, Node.js will either use the directory specified by the + * `NODE_COMPILE_CACHE=dir` environment variable if it's set, or use + * `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. For general use cases, it's + * recommended to call `module.enableCompileCache()` without specifying the `cacheDir`, + * so that the directory can be overridden by the `NODE_COMPILE_CACHE` environment + * variable when necessary. + * + * Since compile cache is supposed to be a quiet optimization that is not required for the + * application to be functional, this method is designed to not throw any exception when the + * compile cache cannot be enabled. Instead, it will return an object containing an error + * message in the `message` field to aid debugging. + * If compile cache is enabled successfully, the `directory` field in the returned object + * contains the path to the directory where the compile cache is stored. The `status` + * field in the returned object would be one of the `module.constants.compileCacheStatus` + * values to indicate the result of the attempt to enable the + * [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache). + * + * This method only affects the current Node.js instance. To enable it in child worker threads, + * either call this method in child worker threads too, or set the + * `process.env.NODE_COMPILE_CACHE` value to compile cache directory so the behavior can + * be inherited into the child workers. The directory can be obtained either from the + * `directory` field returned by this method, or with {@link getCompileCacheDir}. + * @since v22.8.0 + * @param cacheDir Optional path to specify the directory where the compile cache + * will be stored/retrieved. + */ + function enableCompileCache(cacheDir?: string): EnableCompileCacheResult; + /** + * Flush the [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache) + * accumulated from modules already loaded + * in the current Node.js instance to disk. This returns after all the flushing + * file system operations come to an end, no matter they succeed or not. If there + * are any errors, this will fail silently, since compile cache misses should not + * interfere with the actual operation of the application. + * @since v22.10.0 + */ + function flushCompileCache(): void; + /** + * @since v22.8.0 + * @return Path to the [module compile cache](https://nodejs.org/docs/latest-v22.x/api/module.html#module-compile-cache) + * directory if it is enabled, or `undefined` otherwise. + */ + function getCompileCacheDir(): string | undefined; + /** + * ```text + * /path/to/project + * ├ packages/ + * ├ bar/ + * ├ bar.js + * └ package.json // name = '@foo/bar' + * └ qux/ + * ├ node_modules/ + * └ some-package/ + * └ package.json // name = 'some-package' + * ├ qux.js + * └ package.json // name = '@foo/qux' + * ├ main.js + * └ package.json // name = '@foo' + * ``` + * ```js + * // /path/to/project/packages/bar/bar.js + * import { findPackageJSON } from 'node:module'; + * + * findPackageJSON('..', import.meta.url); + * // '/path/to/project/package.json' + * // Same result when passing an absolute specifier instead: + * findPackageJSON(new URL('../', import.meta.url)); + * findPackageJSON(import.meta.resolve('../')); + * + * findPackageJSON('some-package', import.meta.url); + * // '/path/to/project/packages/bar/node_modules/some-package/package.json' + * // When passing an absolute specifier, you might get a different result if the + * // resolved module is inside a subfolder that has nested `package.json`. + * findPackageJSON(import.meta.resolve('some-package')); + * // '/path/to/project/packages/bar/node_modules/some-package/some-subfolder/package.json' + * + * findPackageJSON('@foo/qux', import.meta.url); + * // '/path/to/project/packages/qux/package.json' + * ``` + * @since v22.14.0 + * @param specifier The specifier for the module whose `package.json` to + * retrieve. When passing a _bare specifier_, the `package.json` at the root of + * the package is returned. When passing a _relative specifier_ or an _absolute specifier_, + * the closest parent `package.json` is returned. + * @param base The absolute location (`file:` URL string or FS path) of the + * containing module. For CJS, use `__filename` (not `__dirname`!); for ESM, use + * `import.meta.url`. You do not need to pass it if `specifier` is an _absolute specifier_. + * @returns A path if the `package.json` is found. When `startLocation` + * is a package, the package's root `package.json`; when a relative or unresolved, the closest + * `package.json` to the `startLocation`. + */ + function findPackageJSON(specifier: string | URL, base?: string | URL): string | undefined; + /** + * @since v18.6.0, v16.17.0 + */ + function isBuiltin(moduleName: string): boolean; + interface RegisterOptions { + /** + * If you want to resolve `specifier` relative to a + * base URL, such as `import.meta.url`, you can pass that URL here. This + * property is ignored if the `parentURL` is supplied as the second argument. + * @default 'data:' + */ + parentURL?: string | URL | undefined; + /** + * Any arbitrary, cloneable JavaScript value to pass into the + * {@link initialize} hook. + */ + data?: Data | undefined; + /** + * [Transferable objects](https://nodejs.org/docs/latest-v22.x/api/worker_threads.html#portpostmessagevalue-transferlist) + * to be passed into the `initialize` hook. + */ + transferList?: any[] | undefined; + } + /* eslint-disable @definitelytyped/no-unnecessary-generics */ + /** + * Register a module that exports hooks that customize Node.js module + * resolution and loading behavior. See + * [Customization hooks](https://nodejs.org/docs/latest-v22.x/api/module.html#customization-hooks). + * + * This feature requires `--allow-worker` if used with the + * [Permission Model](https://nodejs.org/docs/latest-v22.x/api/permissions.html#permission-model). + * @since v20.6.0, v18.19.0 + * @param specifier Customization hooks to be registered; this should be + * the same string that would be passed to `import()`, except that if it is + * relative, it is resolved relative to `parentURL`. + * @param parentURL f you want to resolve `specifier` relative to a base + * URL, such as `import.meta.url`, you can pass that URL here. + */ + function register( + specifier: string | URL, + parentURL?: string | URL, + options?: RegisterOptions, + ): void; + function register(specifier: string | URL, options?: RegisterOptions): void; + interface RegisterHooksOptions { + /** + * See [load hook](https://nodejs.org/docs/latest-v22.x/api/module.html#loadurl-context-nextload). + * @default undefined + */ + load?: LoadHookSync | undefined; + /** + * See [resolve hook](https://nodejs.org/docs/latest-v22.x/api/module.html#resolvespecifier-context-nextresolve). + * @default undefined + */ + resolve?: ResolveHookSync | undefined; + } + interface ModuleHooks { + /** + * Deregister the hook instance. + */ + deregister(): void; + } + /** + * Register [hooks](https://nodejs.org/docs/latest-v22.x/api/module.html#customization-hooks) + * that customize Node.js module resolution and loading behavior. + * @since v22.15.0 + * @experimental + */ + function registerHooks(options: RegisterHooksOptions): ModuleHooks; + interface StripTypeScriptTypesOptions { + /** + * Possible values are: + * * `'strip'` Only strip type annotations without performing the transformation of TypeScript features. + * * `'transform'` Strip type annotations and transform TypeScript features to JavaScript. + * @default 'strip' + */ + mode?: "strip" | "transform" | undefined; + /** + * Only when `mode` is `'transform'`, if `true`, a source map + * will be generated for the transformed code. + * @default false + */ + sourceMap?: boolean | undefined; + /** + * Specifies the source url used in the source map. + */ + sourceUrl?: string | undefined; + } + /** + * `module.stripTypeScriptTypes()` removes type annotations from TypeScript code. It + * can be used to strip type annotations from TypeScript code before running it + * with `vm.runInContext()` or `vm.compileFunction()`. + * By default, it will throw an error if the code contains TypeScript features + * that require transformation such as `Enums`, + * see [type-stripping](https://nodejs.org/docs/latest-v22.x/api/typescript.md#type-stripping) for more information. + * When mode is `'transform'`, it also transforms TypeScript features to JavaScript, + * see [transform TypeScript features](https://nodejs.org/docs/latest-v22.x/api/typescript.md#typescript-features) for more information. + * When mode is `'strip'`, source maps are not generated, because locations are preserved. + * If `sourceMap` is provided, when mode is `'strip'`, an error will be thrown. + * + * _WARNING_: The output of this function should not be considered stable across Node.js versions, + * due to changes in the TypeScript parser. + * + * ```js + * import { stripTypeScriptTypes } from 'node:module'; + * const code = 'const a: number = 1;'; + * const strippedCode = stripTypeScriptTypes(code); + * console.log(strippedCode); + * // Prints: const a = 1; + * ``` + * + * If `sourceUrl` is provided, it will be used appended as a comment at the end of the output: + * + * ```js + * import { stripTypeScriptTypes } from 'node:module'; + * const code = 'const a: number = 1;'; + * const strippedCode = stripTypeScriptTypes(code, { mode: 'strip', sourceUrl: 'source.ts' }); + * console.log(strippedCode); + * // Prints: const a = 1\n\n//# sourceURL=source.ts; + * ``` + * + * When `mode` is `'transform'`, the code is transformed to JavaScript: + * + * ```js + * import { stripTypeScriptTypes } from 'node:module'; + * const code = ` + * namespace MathUtil { + * export const add = (a: number, b: number) => a + b; + * }`; + * const strippedCode = stripTypeScriptTypes(code, { mode: 'transform', sourceMap: true }); + * console.log(strippedCode); + * // Prints: + * // var MathUtil; + * // (function(MathUtil) { + * // MathUtil.add = (a, b)=>a + b; + * // })(MathUtil || (MathUtil = {})); + * // # sourceMappingURL=data:application/json;base64, ... + * ``` + * @since v22.13.0 + * @param code The code to strip type annotations from. + * @returns The code with type annotations stripped. + */ + function stripTypeScriptTypes(code: string, options?: StripTypeScriptTypesOptions): string; + /* eslint-enable @definitelytyped/no-unnecessary-generics */ /** * The `module.syncBuiltinESMExports()` method updates all the live bindings for * builtin `ES Modules` to match the properties of the `CommonJS` exports. It @@ -42,111 +356,27 @@ declare module "module" { * @since v12.12.0 */ function syncBuiltinESMExports(): void; - /** - * `path` is the resolved path for the file for which a corresponding source map - * should be fetched. - * @since v13.7.0, v12.17.0 - * @return Returns `module.SourceMap` if a source map is found, `undefined` otherwise. - */ - function findSourceMap(path: string, error?: Error): SourceMap; - interface SourceMapPayload { - file: string; - version: number; - sources: string[]; - sourcesContent: string[]; - names: string[]; - mappings: string; - sourceRoot: string; - } - interface SourceMapping { - generatedLine: number; - generatedColumn: number; - originalSource: string; - originalLine: number; - originalColumn: number; - } - interface SourceOrigin { - /** - * The name of the range in the source map, if one was provided - */ - name?: string; - /** - * The file name of the original source, as reported in the SourceMap - */ - fileName: string; - /** - * The 1-indexed lineNumber of the corresponding call site in the original source - */ - lineNumber: number; - /** - * The 1-indexed columnNumber of the corresponding call site in the original source - */ - columnNumber: number; - } - /** - * @since v13.7.0, v12.17.0 - */ - class SourceMap { - /** - * Getter for the payload used to construct the `SourceMap` instance. - */ - readonly payload: SourceMapPayload; - constructor(payload: SourceMapPayload); - /** - * Given a line offset and column offset in the generated source - * file, returns an object representing the SourceMap range in the - * original file if found, or an empty object if not. - * - * The object returned contains the following keys: - * - * The returned value represents the raw range as it appears in the - * SourceMap, based on zero-indexed offsets, _not_ 1-indexed line and - * column numbers as they appear in Error messages and CallSite - * objects. - * - * To get the corresponding 1-indexed line and column numbers from a - * lineNumber and columnNumber as they are reported by Error stacks - * and CallSite objects, use `sourceMap.findOrigin(lineNumber, columnNumber)` - * @param lineOffset The zero-indexed line number offset in the generated source - * @param columnOffset The zero-indexed column number offset in the generated source - */ - findEntry(lineOffset: number, columnOffset: number): SourceMapping; - /** - * Given a 1-indexed `lineNumber` and `columnNumber` from a call site in the generated source, - * find the corresponding call site location in the original source. - * - * If the `lineNumber` and `columnNumber` provided are not found in any source map, - * then an empty object is returned. - * @param lineNumber The 1-indexed line number of the call site in the generated source - * @param columnNumber The 1-indexed column number of the call site in the generated source - */ - findOrigin(lineNumber: number, columnNumber: number): SourceOrigin | {}; - } interface ImportAttributes extends NodeJS.Dict { type?: string | undefined; } - type ModuleFormat = "builtin" | "commonjs" | "json" | "module" | "wasm"; + type ModuleFormat = + | "builtin" + | "commonjs" + | "commonjs-typescript" + | "json" + | "module" + | "module-typescript" + | "wasm"; type ModuleSource = string | ArrayBuffer | NodeJS.TypedArray; - interface GlobalPreloadContext { - port: MessagePort; - } - /** - * @deprecated This hook will be removed in a future version. - * Use `initialize` instead. When a loader has an `initialize` export, `globalPreload` will be ignored. - * - * Sometimes it might be necessary to run some code inside of the same global scope that the application runs in. - * This hook allows the return of a string that is run as a sloppy-mode script on startup. - * - * @param context Information to assist the preload code - * @return Code to run before application startup - */ - type GlobalPreloadHook = (context: GlobalPreloadContext) => string; /** - * The `initialize` hook provides a way to define a custom function that runs in the hooks thread - * when the hooks module is initialized. Initialization happens when the hooks module is registered via `register`. + * The `initialize` hook provides a way to define a custom function that runs in + * the hooks thread when the hooks module is initialized. Initialization happens + * when the hooks module is registered via {@link register}. * - * This hook can receive data from a `register` invocation, including ports and other transferrable objects. - * The return value of `initialize` can be a `Promise`, in which case it will be awaited before the main application thread execution resumes. + * This hook can receive data from a {@link register} invocation, including + * ports and other transferable objects. The return value of `initialize` can be a + * `Promise`, in which case it will be awaited before the main application thread + * execution resumes. */ type InitializeHook = (data: Data) => void | Promise; interface ResolveHookContext { @@ -165,9 +395,9 @@ declare module "module" { } interface ResolveFnOutput { /** - * A hint to the load hook (it might be ignored) + * A hint to the load hook (it might be ignored); can be an intermediary value. */ - format?: ModuleFormat | null | undefined; + format?: string | null | undefined; /** * The import attributes to use when caching the module (optional; if excluded the input will be used) */ @@ -183,38 +413,46 @@ declare module "module" { url: string; } /** - * The `resolve` hook chain is responsible for resolving file URL for a given module specifier and parent URL, and optionally its format (such as `'module'`) as a hint to the `load` hook. - * If a format is specified, the load hook is ultimately responsible for providing the final `format` value (and it is free to ignore the hint provided by `resolve`); - * if `resolve` provides a format, a custom `load` hook is required even if only to pass the value to the Node.js default `load` hook. - * - * @param specifier The specified URL path of the module to be resolved - * @param context - * @param nextResolve The subsequent `resolve` hook in the chain, or the Node.js default `resolve` hook after the last user-supplied resolve hook + * The `resolve` hook chain is responsible for telling Node.js where to find and + * how to cache a given `import` statement or expression, or `require` call. It can + * optionally return a format (such as `'module'`) as a hint to the `load` hook. If + * a format is specified, the `load` hook is ultimately responsible for providing + * the final `format` value (and it is free to ignore the hint provided by + * `resolve`); if `resolve` provides a `format`, a custom `load` hook is required + * even if only to pass the value to the Node.js default `load` hook. */ type ResolveHook = ( specifier: string, context: ResolveHookContext, nextResolve: ( specifier: string, - context?: ResolveHookContext, + context?: Partial, ) => ResolveFnOutput | Promise, ) => ResolveFnOutput | Promise; + type ResolveHookSync = ( + specifier: string, + context: ResolveHookContext, + nextResolve: ( + specifier: string, + context?: Partial, + ) => ResolveFnOutput, + ) => ResolveFnOutput; interface LoadHookContext { /** * Export conditions of the relevant `package.json` */ conditions: string[]; /** - * The format optionally supplied by the `resolve` hook chain + * The format optionally supplied by the `resolve` hook chain (can be an intermediary value). */ - format: ModuleFormat; + format: string | null | undefined; /** * An object whose key-value pairs represent the assertions for the module to import */ importAttributes: ImportAttributes; } interface LoadFnOutput { - format: ModuleFormat; + format: string | null | undefined; /** * A signal that this hook intends to terminate the chain of `resolve` hooks. * @default false @@ -223,75 +461,403 @@ declare module "module" { /** * The source for Node.js to evaluate */ - source?: ModuleSource; + source?: ModuleSource | undefined; } /** - * The `load` hook provides a way to define a custom method of determining how a URL should be interpreted, retrieved, and parsed. - * It is also in charge of validating the import assertion. - * - * @param url The URL/path of the module to be loaded - * @param context Metadata about the module - * @param nextLoad The subsequent `load` hook in the chain, or the Node.js default `load` hook after the last user-supplied `load` hook + * The `load` hook provides a way to define a custom method of determining how a + * URL should be interpreted, retrieved, and parsed. It is also in charge of + * validating the import attributes. */ type LoadHook = ( url: string, context: LoadHookContext, - nextLoad: (url: string, context?: LoadHookContext) => LoadFnOutput | Promise, + nextLoad: ( + url: string, + context?: Partial, + ) => LoadFnOutput | Promise, ) => LoadFnOutput | Promise; - } - interface RegisterOptions { - parentURL: string | URL; - data?: Data | undefined; - transferList?: any[] | undefined; - } - interface Module extends NodeModule {} - class Module { - static runMain(): void; - static wrap(code: string): string; - static createRequire(path: string | URL): NodeRequire; - static builtinModules: string[]; - static isBuiltin(moduleName: string): boolean; - static Module: typeof Module; - static register( - specifier: string | URL, - parentURL?: string | URL, - options?: RegisterOptions, - ): void; - static register(specifier: string | URL, options?: RegisterOptions): void; - constructor(id: string, parent?: Module); + type LoadHookSync = ( + url: string, + context: LoadHookContext, + nextLoad: ( + url: string, + context?: Partial, + ) => LoadFnOutput, + ) => LoadFnOutput; + interface SourceMapsSupport { + /** + * If the source maps support is enabled + */ + enabled: boolean; + /** + * If the support is enabled for files in `node_modules`. + */ + nodeModules: boolean; + /** + * If the support is enabled for generated code from `eval` or `new Function`. + */ + generatedCode: boolean; + } + /** + * This method returns whether the [Source Map v3](https://tc39.es/ecma426/) support for stack + * traces is enabled. + * @since v22.14.0 + */ + function getSourceMapsSupport(): SourceMapsSupport; + /** + * `path` is the resolved path for the file for which a corresponding source map + * should be fetched. + * @since v13.7.0, v12.17.0 + * @return Returns `module.SourceMap` if a source map is found, `undefined` otherwise. + */ + function findSourceMap(path: string): SourceMap | undefined; + interface SetSourceMapsSupportOptions { + /** + * If enabling the support for files in `node_modules`. + * @default false + */ + nodeModules?: boolean | undefined; + /** + * If enabling the support for generated code from `eval` or `new Function`. + * @default false + */ + generatedCode?: boolean | undefined; + } + /** + * This function enables or disables the [Source Map v3](https://tc39.es/ecma426/) support for + * stack traces. + * + * It provides same features as launching Node.js process with commandline options + * `--enable-source-maps`, with additional options to alter the support for files + * in `node_modules` or generated codes. + * + * Only source maps in JavaScript files that are loaded after source maps has been + * enabled will be parsed and loaded. Preferably, use the commandline options + * `--enable-source-maps` to avoid losing track of source maps of modules loaded + * before this API call. + * @since v22.14.0 + */ + function setSourceMapsSupport(enabled: boolean, options?: SetSourceMapsSupportOptions): void; + interface SourceMapConstructorOptions { + /** + * @since v21.0.0, v20.5.0 + */ + lineLengths?: readonly number[] | undefined; + } + interface SourceMapPayload { + file: string; + version: number; + sources: string[]; + sourcesContent: string[]; + names: string[]; + mappings: string; + sourceRoot: string; + } + interface SourceMapping { + generatedLine: number; + generatedColumn: number; + originalSource: string; + originalLine: number; + originalColumn: number; + } + interface SourceOrigin { + /** + * The name of the range in the source map, if one was provided + */ + name: string | undefined; + /** + * The file name of the original source, as reported in the SourceMap + */ + fileName: string; + /** + * The 1-indexed lineNumber of the corresponding call site in the original source + */ + lineNumber: number; + /** + * The 1-indexed columnNumber of the corresponding call site in the original source + */ + columnNumber: number; + } + /** + * @since v13.7.0, v12.17.0 + */ + class SourceMap { + constructor(payload: SourceMapPayload, options?: SourceMapConstructorOptions); + /** + * Getter for the payload used to construct the `SourceMap` instance. + */ + readonly payload: SourceMapPayload; + /** + * Given a line offset and column offset in the generated source + * file, returns an object representing the SourceMap range in the + * original file if found, or an empty object if not. + * + * The object returned contains the following keys: + * + * The returned value represents the raw range as it appears in the + * SourceMap, based on zero-indexed offsets, _not_ 1-indexed line and + * column numbers as they appear in Error messages and CallSite + * objects. + * + * To get the corresponding 1-indexed line and column numbers from a + * lineNumber and columnNumber as they are reported by Error stacks + * and CallSite objects, use `sourceMap.findOrigin(lineNumber, columnNumber)` + * @param lineOffset The zero-indexed line number offset in the generated source + * @param columnOffset The zero-indexed column number offset in the generated source + */ + findEntry(lineOffset: number, columnOffset: number): SourceMapping | {}; + /** + * Given a 1-indexed `lineNumber` and `columnNumber` from a call site in the generated source, + * find the corresponding call site location in the original source. + * + * If the `lineNumber` and `columnNumber` provided are not found in any source map, + * then an empty object is returned. + * @param lineNumber The 1-indexed line number of the call site in the generated source + * @param columnNumber The 1-indexed column number of the call site in the generated source + */ + findOrigin(lineNumber: number, columnNumber: number): SourceOrigin | {}; + } + function runMain(main?: string): void; + function wrap(script: string): string; } global { interface ImportMeta { /** - * The directory name of the current module. This is the same as the `path.dirname()` of the `import.meta.filename`. - * **Caveat:** only present on `file:` modules. + * The directory name of the current module. + * + * This is the same as the `path.dirname()` of the `import.meta.filename`. + * + * > **Caveat**: only present on `file:` modules. + * @since v21.2.0, v20.11.0 */ dirname: string; /** - * The full absolute path and filename of the current module, with symlinks resolved. + * The full absolute path and filename of the current module, with + * symlinks resolved. + * * This is the same as the `url.fileURLToPath()` of the `import.meta.url`. - * **Caveat:** only local modules support this property. Modules not using the `file:` protocol will not provide it. + * + * > **Caveat** only local modules support this property. Modules not using the + * > `file:` protocol will not provide it. + * @since v21.2.0, v20.11.0 */ filename: string; /** * The absolute `file:` URL of the module. + * + * This is defined exactly the same as it is in browsers providing the URL of the + * current module file. + * + * This enables useful patterns such as relative file loading: + * + * ```js + * import { readFileSync } from 'node:fs'; + * const buffer = readFileSync(new URL('./data.proto', import.meta.url)); + * ``` */ url: string; /** - * Provides a module-relative resolution function scoped to each module, returning - * the URL string. + * `import.meta.resolve` is a module-relative resolution function scoped to + * each module, returning the URL string. * - * Second `parent` parameter is only used when the `--experimental-import-meta-resolve` - * command flag enabled. + * ```js + * const dependencyAsset = import.meta.resolve('component-lib/asset.css'); + * // file:///app/node_modules/component-lib/asset.css + * import.meta.resolve('./dep.js'); + * // file:///app/dep.js + * ``` * - * @since v20.6.0 + * All features of the Node.js module resolution are supported. Dependency + * resolutions are subject to the permitted exports resolutions within the package. * - * @param specifier The module specifier to resolve relative to `parent`. - * @param parent The absolute parent module URL to resolve from. - * @returns The absolute (`file:`) URL string for the resolved module. + * **Caveats**: + * + * * This can result in synchronous file-system operations, which + * can impact performance similarly to `require.resolve`. + * * This feature is not available within custom loaders (it would + * create a deadlock). + * @since v13.9.0, v12.16.0 + * @param specifier The module specifier to resolve relative to the + * current module. + * @param parent An optional absolute parent module URL to resolve from. + * **Default:** `import.meta.url` + * @returns The absolute URL string that the specifier would resolve to. */ - resolve(specifier: string, parent?: string | URL | undefined): string; + resolve(specifier: string, parent?: string | URL): string; + } + namespace NodeJS { + interface Module { + /** + * The module objects required for the first time by this one. + * @since v0.1.16 + */ + children: Module[]; + /** + * The `module.exports` object is created by the `Module` system. Sometimes this is + * not acceptable; many want their module to be an instance of some class. To do + * this, assign the desired export object to `module.exports`. + * @since v0.1.16 + */ + exports: any; + /** + * The fully resolved filename of the module. + * @since v0.1.16 + */ + filename: string; + /** + * The identifier for the module. Typically this is the fully resolved + * filename. + * @since v0.1.16 + */ + id: string; + /** + * `true` if the module is running during the Node.js preload + * phase. + * @since v15.4.0, v14.17.0 + */ + isPreloading: boolean; + /** + * Whether or not the module is done loading, or is in the process of + * loading. + * @since v0.1.16 + */ + loaded: boolean; + /** + * The module that first required this one, or `null` if the current module is the + * entry point of the current process, or `undefined` if the module was loaded by + * something that is not a CommonJS module (e.g. REPL or `import`). + * @since v0.1.16 + * @deprecated Please use `require.main` and `module.children` instead. + */ + parent: Module | null | undefined; + /** + * The directory name of the module. This is usually the same as the + * `path.dirname()` of the `module.id`. + * @since v11.14.0 + */ + path: string; + /** + * The search paths for the module. + * @since v0.4.0 + */ + paths: string[]; + /** + * The `module.require()` method provides a way to load a module as if + * `require()` was called from the original module. + * @since v0.5.1 + */ + require(id: string): any; + } + interface Require { + /** + * Used to import modules, `JSON`, and local files. + * @since v0.1.13 + */ + (id: string): any; + /** + * Modules are cached in this object when they are required. By deleting a key + * value from this object, the next `require` will reload the module. + * This does not apply to + * [native addons](https://nodejs.org/docs/latest-v22.x/api/addons.html), + * for which reloading will result in an error. + * @since v0.3.0 + */ + cache: Dict; + /** + * Instruct `require` on how to handle certain file extensions. + * @since v0.3.0 + * @deprecated + */ + extensions: RequireExtensions; + /** + * The `Module` object representing the entry script loaded when the Node.js + * process launched, or `undefined` if the entry point of the program is not a + * CommonJS module. + * @since v0.1.17 + */ + main: Module | undefined; + /** + * @since v0.3.0 + */ + resolve: RequireResolve; + } + /** @deprecated */ + interface RequireExtensions extends Dict<(module: Module, filename: string) => any> { + ".js": (module: Module, filename: string) => any; + ".json": (module: Module, filename: string) => any; + ".node": (module: Module, filename: string) => any; + } + interface RequireResolveOptions { + /** + * Paths to resolve module location from. If present, these + * paths are used instead of the default resolution paths, with the exception + * of + * [GLOBAL\_FOLDERS](https://nodejs.org/docs/latest-v22.x/api/modules.html#loading-from-the-global-folders) + * like `$HOME/.node_modules`, which are + * always included. Each of these paths is used as a starting point for + * the module resolution algorithm, meaning that the `node_modules` hierarchy + * is checked from this location. + * @since v8.9.0 + */ + paths?: string[] | undefined; + } + interface RequireResolve { + /** + * Use the internal `require()` machinery to look up the location of a module, + * but rather than loading the module, just return the resolved filename. + * + * If the module can not be found, a `MODULE_NOT_FOUND` error is thrown. + * @since v0.3.0 + * @param request The module path to resolve. + */ + (request: string, options?: RequireResolveOptions): string; + /** + * Returns an array containing the paths searched during resolution of `request` or + * `null` if the `request` string references a core module, for example `http` or + * `fs`. + * @since v8.9.0 + * @param request The module path whose lookup paths are being retrieved. + */ + paths(request: string): string[] | null; + } } + /** + * The directory name of the current module. This is the same as the + * `path.dirname()` of the `__filename`. + * @since v0.1.27 + */ + var __dirname: string; + /** + * The file name of the current module. This is the current module file's absolute + * path with symlinks resolved. + * + * For a main program this is not necessarily the same as the file name used in the + * command line. + * @since v0.0.1 + */ + var __filename: string; + /** + * The `exports` variable is available within a module's file-level scope, and is + * assigned the value of `module.exports` before the module is evaluated. + * @since v0.1.16 + */ + var exports: NodeJS.Module["exports"]; + /** + * A reference to the current module. + * @since v0.1.16 + */ + var module: NodeJS.Module; + /** + * @since v0.1.13 + */ + var require: NodeJS.Require; + // Global-scope aliases for backwards compatibility with @types/node <13.0.x + /** @deprecated Use `NodeJS.Module` instead. */ + interface NodeModule extends NodeJS.Module {} + /** @deprecated Use `NodeJS.Require` instead. */ + interface NodeRequire extends NodeJS.Require {} + /** @deprecated Use `NodeJS.RequireResolve` instead. */ + interface RequireResolve extends NodeJS.RequireResolve {} } export = Module; } diff --git a/node_modules/@types/node/net.d.ts b/node_modules/@types/node/net.d.ts index d113e21ff..e1ca2523b 100644 --- a/node_modules/@types/node/net.d.ts +++ b/node_modules/@types/node/net.d.ts @@ -65,6 +65,7 @@ declare module "net" { * @since v18.13.0 */ autoSelectFamilyAttemptTimeout?: number | undefined; + blockList?: BlockList | undefined; } interface IpcSocketConnectOpts { path: string; @@ -108,8 +109,8 @@ declare module "net" { * @since v0.1.90 * @param [encoding='utf8'] Only used when data is `string`. */ - write(buffer: Uint8Array | string, cb?: (err?: Error) => void): boolean; - write(str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error) => void): boolean; + write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean; + write(str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean; /** * Initiate a connection on a given socket. * @@ -376,7 +377,7 @@ declare module "net" { addListener(event: "connectionAttempt", listener: (ip: string, port: number, family: number) => void): this; addListener( event: "connectionAttemptFailed", - listener: (ip: string, port: number, family: number) => void, + listener: (ip: string, port: number, family: number, error: Error) => void, ): this; addListener( event: "connectionAttemptTimeout", @@ -396,7 +397,7 @@ declare module "net" { emit(event: "close", hadError: boolean): boolean; emit(event: "connect"): boolean; emit(event: "connectionAttempt", ip: string, port: number, family: number): boolean; - emit(event: "connectionAttemptFailed", ip: string, port: number, family: number): boolean; + emit(event: "connectionAttemptFailed", ip: string, port: number, family: number, error: Error): boolean; emit(event: "connectionAttemptTimeout", ip: string, port: number, family: number): boolean; emit(event: "data", data: Buffer): boolean; emit(event: "drain"): boolean; @@ -409,7 +410,10 @@ declare module "net" { on(event: "close", listener: (hadError: boolean) => void): this; on(event: "connect", listener: () => void): this; on(event: "connectionAttempt", listener: (ip: string, port: number, family: number) => void): this; - on(event: "connectionAttemptFailed", listener: (ip: string, port: number, family: number) => void): this; + on( + event: "connectionAttemptFailed", + listener: (ip: string, port: number, family: number, error: Error) => void, + ): this; on(event: "connectionAttemptTimeout", listener: (ip: string, port: number, family: number) => void): this; on(event: "data", listener: (data: Buffer) => void): this; on(event: "drain", listener: () => void): this; @@ -424,7 +428,10 @@ declare module "net" { once(event: string, listener: (...args: any[]) => void): this; once(event: "close", listener: (hadError: boolean) => void): this; once(event: "connectionAttempt", listener: (ip: string, port: number, family: number) => void): this; - once(event: "connectionAttemptFailed", listener: (ip: string, port: number, family: number) => void): this; + once( + event: "connectionAttemptFailed", + listener: (ip: string, port: number, family: number, error: Error) => void, + ): this; once(event: "connectionAttemptTimeout", listener: (ip: string, port: number, family: number) => void): this; once(event: "connect", listener: () => void): this; once(event: "data", listener: (data: Buffer) => void): this; @@ -443,7 +450,7 @@ declare module "net" { prependListener(event: "connectionAttempt", listener: (ip: string, port: number, family: number) => void): this; prependListener( event: "connectionAttemptFailed", - listener: (ip: string, port: number, family: number) => void, + listener: (ip: string, port: number, family: number, error: Error) => void, ): this; prependListener( event: "connectionAttemptTimeout", @@ -468,7 +475,7 @@ declare module "net" { ): this; prependOnceListener( event: "connectionAttemptFailed", - listener: (ip: string, port: number, family: number) => void, + listener: (ip: string, port: number, family: number, error: Error) => void, ): this; prependOnceListener( event: "connectionAttemptTimeout", @@ -486,17 +493,18 @@ declare module "net" { prependOnceListener(event: "timeout", listener: () => void): this; } interface ListenOptions extends Abortable { - port?: number | undefined; - host?: string | undefined; backlog?: number | undefined; - path?: string | undefined; exclusive?: boolean | undefined; - readableAll?: boolean | undefined; - writableAll?: boolean | undefined; + host?: string | undefined; /** * @default false */ ipv6Only?: boolean | undefined; + reusePort?: boolean | undefined; + path?: string | undefined; + port?: number | undefined; + readableAll?: boolean | undefined; + writableAll?: boolean | undefined; } interface ServerOpts { /** @@ -534,6 +542,15 @@ declare module "net" { * @since v18.17.0, v20.1.0 */ highWaterMark?: number | undefined; + /** + * `blockList` can be used for disabling inbound + * access to specific IP addresses, IP ranges, or IP subnets. This does not + * work if the server is behind a reverse proxy, NAT, etc. because the address + * checked against the block list is the address of the proxy, or the one + * specified by the NAT. + * @since v22.13.0 + */ + blockList?: BlockList | undefined; } interface DropArgument { localAddress?: string; @@ -645,7 +662,7 @@ declare module "net" { * Callback should take two arguments `err` and `count`. * @since v0.9.7 */ - getConnections(cb: (error: Error | null, count: number) => void): void; + getConnections(cb: (error: Error | null, count: number) => void): this; /** * Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will _not_ let the program exit if it's the only server left (the default behavior). * If the server is `ref`ed calling `ref()` again will have no effect. @@ -785,6 +802,12 @@ declare module "net" { * @since v15.0.0, v14.18.0 */ rules: readonly string[]; + /** + * Returns `true` if the `value` is a `net.BlockList`. + * @since v22.13.0 + * @param value Any JS value + */ + static isBlockList(value: unknown): value is BlockList; } interface TcpNetConnectOpts extends TcpSocketConnectOpts, SocketConstructorOpts { timeout?: number | undefined; @@ -896,6 +919,9 @@ declare module "net" { function getDefaultAutoSelectFamily(): boolean; /** * Sets the default value of the `autoSelectFamily` option of `socket.connect(options)`. + * @param value The new default value. + * The initial default value is `true`, unless the command line option + * `--no-network-family-autoselection` is provided. * @since v19.4.0 */ function setDefaultAutoSelectFamily(value: boolean): void; @@ -994,6 +1020,14 @@ declare module "net" { * @since v15.14.0, v14.18.0 */ readonly flowlabel: number; + /** + * @since v22.13.0 + * @param input An input string containing an IP address and optional port, + * e.g. `123.1.2.3:1234` or `[1::1]:1234`. + * @returns Returns a `SocketAddress` if parsing was successful. + * Otherwise returns `undefined`. + */ + static parse(input: string): SocketAddress | undefined; } } declare module "node:net" { diff --git a/node_modules/@types/node/package.json b/node_modules/@types/node/package.json index 2d9db6c6f..64e9a0080 100644 --- a/node_modules/@types/node/package.json +++ b/node_modules/@types/node/package.json @@ -1,6 +1,6 @@ { "name": "@types/node", - "version": "22.7.9", + "version": "22.17.2", "description": "TypeScript definitions for node", "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node", "license": "MIT", @@ -15,11 +15,6 @@ "githubUsername": "jkomyno", "url": "https://github.com/jkomyno" }, - { - "name": "Alvis HT Tang", - "githubUsername": "alvis", - "url": "https://github.com/alvis" - }, { "name": "Andrew Makarov", "githubUsername": "r3nya", @@ -30,56 +25,11 @@ "githubUsername": "btoueg", "url": "https://github.com/btoueg" }, - { - "name": "Chigozirim C.", - "githubUsername": "smac89", - "url": "https://github.com/smac89" - }, { "name": "David Junger", "githubUsername": "touffy", "url": "https://github.com/touffy" }, - { - "name": "Deividas Bakanas", - "githubUsername": "DeividasBakanas", - "url": "https://github.com/DeividasBakanas" - }, - { - "name": "Eugene Y. Q. Shen", - "githubUsername": "eyqs", - "url": "https://github.com/eyqs" - }, - { - "name": "Hannes Magnusson", - "githubUsername": "Hannes-Magnusson-CK", - "url": "https://github.com/Hannes-Magnusson-CK" - }, - { - "name": "Huw", - "githubUsername": "hoo29", - "url": "https://github.com/hoo29" - }, - { - "name": "Kelvin Jin", - "githubUsername": "kjin", - "url": "https://github.com/kjin" - }, - { - "name": "Klaus Meinhardt", - "githubUsername": "ajafff", - "url": "https://github.com/ajafff" - }, - { - "name": "Lishude", - "githubUsername": "islishude", - "url": "https://github.com/islishude" - }, - { - "name": "Mariusz Wiktorczyk", - "githubUsername": "mwiktorczyk", - "url": "https://github.com/mwiktorczyk" - }, { "name": "Mohsen Azimi", "githubUsername": "mohsen1", @@ -90,46 +40,16 @@ "githubUsername": "galkin", "url": "https://github.com/galkin" }, - { - "name": "Parambir Singh", - "githubUsername": "parambirs", - "url": "https://github.com/parambirs" - }, { "name": "Sebastian Silbermann", "githubUsername": "eps1lon", "url": "https://github.com/eps1lon" }, - { - "name": "Thomas den Hollander", - "githubUsername": "ThomasdenH", - "url": "https://github.com/ThomasdenH" - }, { "name": "Wilco Bakker", "githubUsername": "WilcoBakker", "url": "https://github.com/WilcoBakker" }, - { - "name": "wwwy3y3", - "githubUsername": "wwwy3y3", - "url": "https://github.com/wwwy3y3" - }, - { - "name": "Samuel Ainsworth", - "githubUsername": "samuela", - "url": "https://github.com/samuela" - }, - { - "name": "Kyle Uehlein", - "githubUsername": "kuehlein", - "url": "https://github.com/kuehlein" - }, - { - "name": "Thanik Bhongbhibhat", - "githubUsername": "bhongy", - "url": "https://github.com/bhongy" - }, { "name": "Marcin Kopacz", "githubUsername": "chyzwar", @@ -170,11 +90,6 @@ "githubUsername": "victorperin", "url": "https://github.com/victorperin" }, - { - "name": "Yongsheng Zhang", - "githubUsername": "ZYSzys", - "url": "https://github.com/ZYSzys" - }, { "name": "NodeJS Contributors", "githubUsername": "NodeJS", @@ -199,6 +114,11 @@ "name": "Dmitry Semigradsky", "githubUsername": "Semigradsky", "url": "https://github.com/Semigradsky" + }, + { + "name": "René", + "githubUsername": "Renegade334", + "url": "https://github.com/Renegade334" } ], "main": "", @@ -217,9 +137,9 @@ }, "scripts": {}, "dependencies": { - "undici-types": "~6.19.2" + "undici-types": "~6.21.0" }, "peerDependencies": {}, - "typesPublisherContentHash": "49b712614616bc7f8a0b0f6596d6add73e659a4a4d0695f61e4ab90a468876d3", - "typeScriptVersion": "4.8" + "typesPublisherContentHash": "a7ff7b5fd49b1c228d93a18f6beef30240317965773e258dde1569f20f24658d", + "typeScriptVersion": "5.2" } \ No newline at end of file diff --git a/node_modules/@types/node/perf_hooks.d.ts b/node_modules/@types/node/perf_hooks.d.ts index bffdd3eec..d49460b17 100644 --- a/node_modules/@types/node/perf_hooks.d.ts +++ b/node_modules/@types/node/perf_hooks.d.ts @@ -116,6 +116,20 @@ declare module "perf_hooks" { class PerformanceMeasure extends PerformanceEntry { readonly entryType: "measure"; } + interface UVMetrics { + /** + * Number of event loop iterations. + */ + readonly loopCount: number; + /** + * Number of events that have been processed by the event handler. + */ + readonly events: number; + /** + * Number of events that were waiting to be processed when the event provider was called. + */ + readonly eventsWaiting: number; + } /** * _This property is an extension by Node.js. It is not available in Web browsers._ * @@ -166,6 +180,16 @@ declare module "perf_hooks" { * @since v8.5.0 */ readonly nodeStart: number; + /** + * This is a wrapper to the `uv_metrics_info` function. + * It returns the current set of event loop metrics. + * + * It is recommended to use this property inside a function whose execution was + * scheduled using `setImmediate` to avoid collecting metrics before finishing all + * operations scheduled during the current loop iteration. + * @since v22.8.0, v20.18.0 + */ + readonly uvMetricsInfo: UVMetrics; /** * The high resolution millisecond timestamp at which the V8 platform was * initialized. @@ -570,6 +594,11 @@ declare module "perf_hooks" { buffered?: boolean | undefined; }, ): void; + /** + * @since v16.0.0 + * @returns Current list of entries stored in the performance observer, emptying it out. + */ + takeRecords(): PerformanceEntry[]; } /** * Provides detailed network timing data regarding the loading of an application's resources. @@ -837,12 +866,12 @@ declare module "perf_hooks" { * The minimum recordable value. Must be an integer value greater than 0. * @default 1 */ - min?: number | bigint | undefined; + lowest?: number | bigint | undefined; /** * The maximum recordable value. Must be an integer value greater than min. * @default Number.MAX_SAFE_INTEGER */ - max?: number | bigint | undefined; + highest?: number | bigint | undefined; /** * The number of accuracy digits. Must be a number between 1 and 5. * @default 3 diff --git a/node_modules/@types/node/process.d.ts b/node_modules/@types/node/process.d.ts index e7fd20bb9..0a9f3a657 100644 --- a/node_modules/@types/node/process.d.ts +++ b/node_modules/@types/node/process.d.ts @@ -168,6 +168,83 @@ declare module "process" { libUrl?: string | undefined; lts?: string | undefined; } + interface ProcessFeatures { + /** + * A boolean value that is `true` if the current Node.js build is caching builtin modules. + * @since v12.0.0 + */ + readonly cached_builtins: boolean; + /** + * A boolean value that is `true` if the current Node.js build is a debug build. + * @since v0.5.5 + */ + readonly debug: boolean; + /** + * A boolean value that is `true` if the current Node.js build includes the inspector. + * @since v11.10.0 + */ + readonly inspector: boolean; + /** + * A boolean value that is `true` if the current Node.js build includes support for IPv6. + * + * Since all Node.js builds have IPv6 support, this value is always `true`. + * @since v0.5.3 + * @deprecated This property is always true, and any checks based on it are redundant. + */ + readonly ipv6: boolean; + /** + * A boolean value that is `true` if the current Node.js build supports + * [loading ECMAScript modules using `require()`](https://nodejs.org/docs/latest-v22.x/api/modules.md#loading-ecmascript-modules-using-require). + * @since v22.10.0 + */ + readonly require_module: boolean; + /** + * A boolean value that is `true` if the current Node.js build includes support for TLS. + * @since v0.5.3 + */ + readonly tls: boolean; + /** + * A boolean value that is `true` if the current Node.js build includes support for ALPN in TLS. + * + * In Node.js 11.0.0 and later versions, the OpenSSL dependencies feature unconditional ALPN support. + * This value is therefore identical to that of `process.features.tls`. + * @since v4.8.0 + * @deprecated Use `process.features.tls` instead. + */ + readonly tls_alpn: boolean; + /** + * A boolean value that is `true` if the current Node.js build includes support for OCSP in TLS. + * + * In Node.js 11.0.0 and later versions, the OpenSSL dependencies feature unconditional OCSP support. + * This value is therefore identical to that of `process.features.tls`. + * @since v0.11.13 + * @deprecated Use `process.features.tls` instead. + */ + readonly tls_ocsp: boolean; + /** + * A boolean value that is `true` if the current Node.js build includes support for SNI in TLS. + * + * In Node.js 11.0.0 and later versions, the OpenSSL dependencies feature unconditional SNI support. + * This value is therefore identical to that of `process.features.tls`. + * @since v0.5.3 + * @deprecated Use `process.features.tls` instead. + */ + readonly tls_sni: boolean; + /** + * A value that is `"strip"` if Node.js is run with `--experimental-strip-types`, + * `"transform"` if Node.js is run with `--experimental-transform-types`, and `false` otherwise. + * @since v22.10.0 + */ + readonly typescript: "strip" | "transform" | false; + /** + * A boolean value that is `true` if the current Node.js build includes support for libuv. + * + * Since it's not possible to build Node.js without libuv, this value is always `true`. + * @since v0.5.3 + * @deprecated This property is always true, and any checks based on it are redundant. + */ + readonly uv: boolean; + } interface ProcessVersions extends Dict { http_parser: string; node: string; @@ -273,11 +350,43 @@ declare module "process" { TZ?: string; } interface HRTime { + /** + * This is the legacy version of {@link process.hrtime.bigint()} + * before bigint was introduced in JavaScript. + * + * The `process.hrtime()` method returns the current high-resolution real time in a `[seconds, nanoseconds]` tuple `Array`, + * where `nanoseconds` is the remaining part of the real time that can't be represented in second precision. + * + * `time` is an optional parameter that must be the result of a previous `process.hrtime()` call to diff with the current time. + * If the parameter passed in is not a tuple `Array`, a TypeError will be thrown. + * Passing in a user-defined array instead of the result of a previous call to `process.hrtime()` will lead to undefined behavior. + * + * These times are relative to an arbitrary time in the past, + * and not related to the time of day and therefore not subject to clock drift. + * The primary use is for measuring performance between intervals: + * ```js + * const { hrtime } = require('node:process'); + * const NS_PER_SEC = 1e9; + * const time = hrtime(); + * // [ 1800216, 25 ] + * + * setTimeout(() => { + * const diff = hrtime(time); + * // [ 1, 552 ] + * + * console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`); + * // Benchmark took 1000000552 nanoseconds + * }, 1000); + * ``` + * @since 0.7.6 + * @legacy Use {@link process.hrtime.bigint()} instead. + * @param time The result of a previous call to `process.hrtime()` + */ (time?: [number, number]): [number, number]; /** - * The `bigint` version of the `{@link hrtime()}` method returning the current high-resolution real time in nanoseconds as a `bigint`. + * The `bigint` version of the {@link process.hrtime()} method returning the current high-resolution real time in nanoseconds as a `bigint`. * - * Unlike `{@link hrtime()}`, it does not support an additional time argument since the difference can just be computed directly by subtraction of the two `bigint`s. + * Unlike {@link process.hrtime()}, it does not support an additional time argument since the difference can just be computed directly by subtraction of the two `bigint`s. * ```js * import { hrtime } from 'node:process'; * @@ -292,6 +401,7 @@ declare module "process" { * // Benchmark took 1154389282 nanoseconds * }, 1000); * ``` + * @since v10.7.0 */ bigint(): bigint; } @@ -1456,13 +1566,11 @@ declare module "process" { * See [`uv_get_constrained_memory`](https://docs.libuv.org/en/v1.x/misc.html#c.uv_get_constrained_memory) for more * information. * @since v19.6.0, v18.15.0 - * @experimental */ constrainedMemory(): number; /** * Gets the amount of free memory that is still available to the process (in bytes). * See [`uv_get_available_memory`](https://nodejs.org/docs/latest-v22.x/api/process.html#processavailablememory) for more information. - * @experimental * @since v20.13.0 */ availableMemory(): number; @@ -1583,7 +1691,7 @@ declare module "process" { */ nextTick(callback: Function, ...args: any[]): void; /** - * This API is available through the [--experimental-permission](https://nodejs.org/api/cli.html#--experimental-permission) flag. + * This API is available through the [--permission](https://nodejs.org/api/cli.html#--permission) flag. * * `process.permission` is an object whose methods are used to manage permissions for the current process. * Additional documentation is available in the [Permission Model](https://nodejs.org/api/permissions.html#permission-model). @@ -1612,16 +1720,7 @@ declare module "process" { * @since v3.0.0 */ readonly release: ProcessRelease; - features: { - inspector: boolean; - debug: boolean; - uv: boolean; - ipv6: boolean; - tls_alpn: boolean; - tls_sni: boolean; - tls_ocsp: boolean; - tls: boolean; - }; + readonly features: ProcessFeatures; /** * `process.umask()` returns the Node.js process's file mode creation mask. Child * processes inherit the mask from the parent process. @@ -1809,6 +1908,56 @@ declare module "process" { * @since v0.8.0 */ traceDeprecation: boolean; + /** + * An object is "refable" if it implements the Node.js "Refable protocol". + * Specifically, this means that the object implements the `Symbol.for('nodejs.ref')` + * and `Symbol.for('nodejs.unref')` methods. "Ref'd" objects will keep the Node.js + * event loop alive, while "unref'd" objects will not. Historically, this was + * implemented by using `ref()` and `unref()` methods directly on the objects. + * This pattern, however, is being deprecated in favor of the "Refable protocol" + * in order to better support Web Platform API types whose APIs cannot be modified + * to add `ref()` and `unref()` methods but still need to support that behavior. + * @since v22.14.0 + * @experimental + * @param maybeRefable An object that may be "refable". + */ + ref(maybeRefable: any): void; + /** + * An object is "unrefable" if it implements the Node.js "Refable protocol". + * Specifically, this means that the object implements the `Symbol.for('nodejs.ref')` + * and `Symbol.for('nodejs.unref')` methods. "Ref'd" objects will keep the Node.js + * event loop alive, while "unref'd" objects will not. Historically, this was + * implemented by using `ref()` and `unref()` methods directly on the objects. + * This pattern, however, is being deprecated in favor of the "Refable protocol" + * in order to better support Web Platform API types whose APIs cannot be modified + * to add `ref()` and `unref()` methods but still need to support that behavior. + * @since v22.14.0 + * @experimental + * @param maybeRefable An object that may be "unref'd". + */ + unref(maybeRefable: any): void; + /** + * Replaces the current process with a new process. + * + * This is achieved by using the `execve` POSIX function and therefore no memory or other + * resources from the current process are preserved, except for the standard input, + * standard output and standard error file descriptor. + * + * All other resources are discarded by the system when the processes are swapped, without triggering + * any exit or close events and without running any cleanup handler. + * + * This function will never return, unless an error occurred. + * + * This function is not available on Windows or IBM i. + * @since v22.15.0 + * @experimental + * @param file The name or path of the executable file to run. + * @param args List of string arguments. No argument can contain a null-byte (`\u0000`). + * @param env Environment key-value pairs. + * No key or value can contain a null-byte (`\u0000`). + * **Default:** `process.env`. + */ + execve?(file: string, args?: readonly string[], env?: ProcessEnv): never; /* EventEmitter */ addListener(event: "beforeExit", listener: BeforeExitListener): this; addListener(event: "disconnect", listener: DisconnectListener): this; diff --git a/node_modules/@types/node/querystring.d.ts b/node_modules/@types/node/querystring.d.ts index 4d6dac18d..f0d525701 100644 --- a/node_modules/@types/node/querystring.d.ts +++ b/node_modules/@types/node/querystring.d.ts @@ -37,9 +37,8 @@ declare module "querystring" { | string | number | boolean - | readonly string[] - | readonly number[] - | readonly boolean[] + | bigint + | ReadonlyArray | null > {} diff --git a/node_modules/@types/node/readline.d.ts b/node_modules/@types/node/readline.d.ts index b706a8790..338972e78 100644 --- a/node_modules/@types/node/readline.d.ts +++ b/node_modules/@types/node/readline.d.ts @@ -51,7 +51,7 @@ declare module "readline" { * and is read from, the `input` stream. * @since v0.1.104 */ - export class Interface extends EventEmitter { + export class Interface extends EventEmitter implements Disposable { readonly terminal: boolean; /** * The current input data being processed by node. @@ -208,6 +208,11 @@ declare module "readline" { * @since v0.1.98 */ close(): void; + /** + * Alias for `rl.close()`. + * @since v22.15.0 + */ + [Symbol.dispose](): void; /** * The `rl.write()` method will write either `data` or a key sequence identified * by `key` to the `output`. The `key` argument is supported only if `output` is @@ -314,29 +319,78 @@ declare module "readline" { ) => void; export type CompleterResult = [string[], string]; export interface ReadLineOptions { + /** + * The [`Readable`](https://nodejs.org/docs/latest-v22.x/api/stream.html#readable-streams) stream to listen to + */ input: NodeJS.ReadableStream; + /** + * The [`Writable`](https://nodejs.org/docs/latest-v22.x/api/stream.html#writable-streams) stream to write readline data to. + */ output?: NodeJS.WritableStream | undefined; + /** + * An optional function used for Tab autocompletion. + */ completer?: Completer | AsyncCompleter | undefined; + /** + * `true` if the `input` and `output` streams should be treated like a TTY, + * and have ANSI/VT100 escape codes written to it. + * Default: checking `isTTY` on the `output` stream upon instantiation. + */ terminal?: boolean | undefined; /** - * Initial list of history lines. This option makes sense - * only if `terminal` is set to `true` by the user or by an internal `output` - * check, otherwise the history caching mechanism is not initialized at all. + * Initial list of history lines. + * This option makes sense only if `terminal` is set to `true` by the user or by an internal `output` check, + * otherwise the history caching mechanism is not initialized at all. * @default [] */ history?: string[] | undefined; + /** + * Maximum number of history lines retained. + * To disable the history set this value to `0`. + * This option makes sense only if `terminal` is set to `true` by the user or by an internal `output` check, + * otherwise the history caching mechanism is not initialized at all. + * @default 30 + */ historySize?: number | undefined; - prompt?: string | undefined; - crlfDelay?: number | undefined; /** - * If `true`, when a new input line added - * to the history list duplicates an older one, this removes the older line - * from the list. + * If `true`, when a new input line added to the history list duplicates an older one, + * this removes the older line from the list. * @default false */ removeHistoryDuplicates?: boolean | undefined; + /** + * The prompt string to use. + * @default "> " + */ + prompt?: string | undefined; + /** + * If the delay between `\r` and `\n` exceeds `crlfDelay` milliseconds, + * both `\r` and `\n` will be treated as separate end-of-line input. + * `crlfDelay` will be coerced to a number no less than `100`. + * It can be set to `Infinity`, in which case + * `\r` followed by `\n` will always be considered a single newline + * (which may be reasonable for [reading files](https://nodejs.org/docs/latest-v22.x/api/readline.html#example-read-file-stream-line-by-line) with `\r\n` line delimiter). + * @default 100 + */ + crlfDelay?: number | undefined; + /** + * The duration `readline` will wait for a character + * (when reading an ambiguous key sequence in milliseconds + * one that can both form a complete key sequence using the input read so far + * and can take additional input to complete a longer key sequence). + * @default 500 + */ escapeCodeTimeout?: number | undefined; + /** + * The number of spaces a tab is equal to (minimum 1). + * @default 8 + */ tabSize?: number | undefined; + /** + * Allows closing the interface using an AbortSignal. + * Aborting the signal will internally call `close` on the interface. + */ + signal?: AbortSignal | undefined; } /** * The `readline.createInterface()` method creates a new `readline.Interface` instance. diff --git a/node_modules/@types/node/readline/promises.d.ts b/node_modules/@types/node/readline/promises.d.ts index 4d4310656..c0ebf4ba5 100644 --- a/node_modules/@types/node/readline/promises.d.ts +++ b/node_modules/@types/node/readline/promises.d.ts @@ -1,10 +1,14 @@ /** * @since v17.0.0 - * @experimental */ declare module "readline/promises" { - import { AsyncCompleter, Completer, Direction, Interface as _Interface, ReadLineOptions } from "node:readline"; import { Abortable } from "node:events"; + import { + CompleterResult, + Direction, + Interface as _Interface, + ReadLineOptions as _ReadLineOptions, + } from "node:readline"; /** * Instances of the `readlinePromises.Interface` class are constructed using the `readlinePromises.createInterface()` method. Every instance is associated with a * single `input` `Readable` stream and a single `output` `Writable` stream. @@ -111,6 +115,13 @@ declare module "readline/promises" { */ rollback(): this; } + type Completer = (line: string) => CompleterResult | Promise; + interface ReadLineOptions extends Omit<_ReadLineOptions, "completer"> { + /** + * An optional function used for Tab autocompletion. + */ + completer?: Completer | undefined; + } /** * The `readlinePromises.createInterface()` method creates a new `readlinePromises.Interface` instance. * @@ -140,7 +151,7 @@ declare module "readline/promises" { function createInterface( input: NodeJS.ReadableStream, output?: NodeJS.WritableStream, - completer?: Completer | AsyncCompleter, + completer?: Completer, terminal?: boolean, ): Interface; function createInterface(options: ReadLineOptions): Interface; diff --git a/node_modules/@types/node/repl.d.ts b/node_modules/@types/node/repl.d.ts index 5ff046ada..fb858da14 100644 --- a/node_modules/@types/node/repl.d.ts +++ b/node_modules/@types/node/repl.d.ts @@ -37,12 +37,10 @@ declare module "repl" { terminal?: boolean | undefined; /** * The function to be used when evaluating each given line of input. - * Default: an async wrapper for the JavaScript `eval()` function. An `eval` function can + * **Default:** an async wrapper for the JavaScript `eval()` function. An `eval` function can * error with `repl.Recoverable` to indicate the input was incomplete and prompt for - * additional lines. - * - * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_default_evaluation - * @see https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#repl_custom_evaluation_functions + * additional lines. See the [custom evaluation functions](https://nodejs.org/dist/latest-v22.x/docs/api/repl.html#custom-evaluation-functions) + * section for more details. */ eval?: REPLEval | undefined; /** diff --git a/node_modules/@types/node/sea.d.ts b/node_modules/@types/node/sea.d.ts index 0bedc625e..301307476 100644 --- a/node_modules/@types/node/sea.d.ts +++ b/node_modules/@types/node/sea.d.ts @@ -149,5 +149,5 @@ declare module "node:sea" { * writes to the returned array buffer is likely to result in a crash. * @since v20.12.0 */ - function getRawAsset(key: AssetKey): string | ArrayBuffer; + function getRawAsset(key: AssetKey): ArrayBuffer; } diff --git a/node_modules/@types/node/sqlite.d.ts b/node_modules/@types/node/sqlite.d.ts index 9fa7babb4..4e76b7a6e 100644 --- a/node_modules/@types/node/sqlite.d.ts +++ b/node_modules/@types/node/sqlite.d.ts @@ -10,7 +10,7 @@ * work: * * ```js - * import sqlite from 'node:sqlite'; + * import sqlite from 'sqlite'; * ``` * * The following example shows the basic usage of the `node:sqlite` module to open @@ -43,34 +43,232 @@ * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/sqlite.js) */ declare module "node:sqlite" { + type SQLInputValue = null | number | bigint | string | NodeJS.ArrayBufferView; + type SQLOutputValue = null | number | bigint | string | Uint8Array; + /** @deprecated Use `SQLInputValue` or `SQLOutputValue` instead. */ + type SupportedValueType = SQLOutputValue; interface DatabaseSyncOptions { /** - * If `true`, the database is opened by the constructor. - * When this value is `false`, the database must be opened via the `open()` method. + * If `true`, the database is opened by the constructor. When + * this value is `false`, the database must be opened via the `open()` method. + * @since v22.5.0 + * @default true */ open?: boolean | undefined; + /** + * If `true`, foreign key constraints + * are enabled. This is recommended but can be disabled for compatibility with + * legacy database schemas. The enforcement of foreign key constraints can be + * enabled and disabled after opening the database using + * [`PRAGMA foreign_keys`](https://www.sqlite.org/pragma.html#pragma_foreign_keys). + * @since v22.10.0 + * @default true + */ + enableForeignKeyConstraints?: boolean | undefined; + /** + * If `true`, SQLite will accept + * [double-quoted string literals](https://www.sqlite.org/quirks.html#dblquote). + * This is not recommended but can be + * enabled for compatibility with legacy database schemas. + * @since v22.10.0 + * @default false + */ + enableDoubleQuotedStringLiterals?: boolean | undefined; + /** + * If `true`, the database is opened in read-only mode. + * If the database does not exist, opening it will fail. + * @since v22.12.0 + * @default false + */ + readOnly?: boolean | undefined; + /** + * If `true`, the `loadExtension` SQL function + * and the `loadExtension()` method are enabled. + * You can call `enableLoadExtension(false)` later to disable this feature. + * @since v22.13.0 + * @default false + */ + allowExtension?: boolean | undefined; + } + interface CreateSessionOptions { + /** + * A specific table to track changes for. By default, changes to all tables are tracked. + * @since v22.12.0 + */ + table?: string | undefined; + /** + * Name of the database to track. This is useful when multiple databases have been added using + * [`ATTACH DATABASE`](https://www.sqlite.org/lang_attach.html). + * @since v22.12.0 + * @default 'main' + */ + db?: string | undefined; + } + interface ApplyChangesetOptions { + /** + * Skip changes that, when targeted table name is supplied to this function, return a truthy value. + * By default, all changes are attempted. + * @since v22.12.0 + */ + filter?: ((tableName: string) => boolean) | undefined; + /** + * A function that determines how to handle conflicts. The function receives one argument, + * which can be one of the following values: + * + * * `SQLITE_CHANGESET_DATA`: A `DELETE` or `UPDATE` change does not contain the expected "before" values. + * * `SQLITE_CHANGESET_NOTFOUND`: A row matching the primary key of the `DELETE` or `UPDATE` change does not exist. + * * `SQLITE_CHANGESET_CONFLICT`: An `INSERT` change results in a duplicate primary key. + * * `SQLITE_CHANGESET_FOREIGN_KEY`: Applying a change would result in a foreign key violation. + * * `SQLITE_CHANGESET_CONSTRAINT`: Applying a change results in a `UNIQUE`, `CHECK`, or `NOT NULL` constraint + * violation. + * + * The function should return one of the following values: + * + * * `SQLITE_CHANGESET_OMIT`: Omit conflicting changes. + * * `SQLITE_CHANGESET_REPLACE`: Replace existing values with conflicting changes (only valid with + `SQLITE_CHANGESET_DATA` or `SQLITE_CHANGESET_CONFLICT` conflicts). + * * `SQLITE_CHANGESET_ABORT`: Abort on conflict and roll back the database. + * + * When an error is thrown in the conflict handler or when any other value is returned from the handler, + * applying the changeset is aborted and the database is rolled back. + * + * **Default**: A function that returns `SQLITE_CHANGESET_ABORT`. + * @since v22.12.0 + */ + onConflict?: ((conflictType: number) => number) | undefined; + } + interface FunctionOptions { + /** + * If `true`, the [`SQLITE_DETERMINISTIC`](https://www.sqlite.org/c3ref/c_deterministic.html) flag is + * set on the created function. + * @default false + */ + deterministic?: boolean | undefined; + /** + * If `true`, the [`SQLITE_DIRECTONLY`](https://www.sqlite.org/c3ref/c_directonly.html) flag is set on + * the created function. + * @default false + */ + directOnly?: boolean | undefined; + /** + * If `true`, integer arguments to `function` + * are converted to `BigInt`s. If `false`, integer arguments are passed as + * JavaScript numbers. + * @default false + */ + useBigIntArguments?: boolean | undefined; + /** + * If `true`, `function` may be invoked with any number of + * arguments (between zero and + * [`SQLITE_MAX_FUNCTION_ARG`](https://www.sqlite.org/limits.html#max_function_arg)). If `false`, + * `function` must be invoked with exactly `function.length` arguments. + * @default false + */ + varargs?: boolean | undefined; + } + interface AggregateOptions extends FunctionOptions { + /** + * The identity value for the aggregation function. This value is used when the aggregation + * function is initialized. When a `Function` is passed the identity will be its return value. + */ + start: T | (() => T); + /** + * The function to call for each row in the aggregation. The + * function receives the current state and the row value. The return value of + * this function should be the new state. + */ + step: (accumulator: T, ...args: SQLOutputValue[]) => T; + /** + * The function to call to get the result of the + * aggregation. The function receives the final state and should return the + * result of the aggregation. + */ + result?: ((accumulator: T) => SQLInputValue) | undefined; + /** + * When this function is provided, the `aggregate` method will work as a window function. + * The function receives the current state and the dropped row value. The return value of this function should be the + * new state. + */ + inverse?: ((accumulator: T, ...args: SQLOutputValue[]) => T) | undefined; } /** * This class represents a single [connection](https://www.sqlite.org/c3ref/sqlite3.html) to a SQLite database. All APIs * exposed by this class execute synchronously. * @since v22.5.0 */ - class DatabaseSync { + class DatabaseSync implements Disposable { /** * Constructs a new `DatabaseSync` instance. - * @param location The location of the database. + * @param path The path of the database. * A SQLite database can be stored in a file or completely [in memory](https://www.sqlite.org/inmemorydb.html). - * To use a file-backed database, the location should be a file path. - * To use an in-memory database, the location should be the special name `':memory:'`. + * To use a file-backed database, the path should be a file path. + * To use an in-memory database, the path should be the special name `':memory:'`. * @param options Configuration options for the database connection. */ - constructor(location: string, options?: DatabaseSyncOptions); + constructor(path: string | Buffer | URL, options?: DatabaseSyncOptions); + /** + * Registers a new aggregate function with the SQLite database. This method is a wrapper around + * [`sqlite3_create_window_function()`](https://www.sqlite.org/c3ref/create_function.html). + * + * When used as a window function, the `result` function will be called multiple times. + * + * ```js + * import { DatabaseSync } from 'node:sqlite'; + * + * const db = new DatabaseSync(':memory:'); + * db.exec(` + * CREATE TABLE t3(x, y); + * INSERT INTO t3 VALUES ('a', 4), + * ('b', 5), + * ('c', 3), + * ('d', 8), + * ('e', 1); + * `); + * + * db.aggregate('sumint', { + * start: 0, + * step: (acc, value) => acc + value, + * }); + * + * db.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 } + * ``` + * @since v22.16.0 + * @param name The name of the SQLite function to create. + * @param options Function configuration settings. + */ + aggregate(name: string, options: AggregateOptions): void; + aggregate(name: string, options: AggregateOptions): void; /** * Closes the database connection. An exception is thrown if the database is not * open. This method is a wrapper around [`sqlite3_close_v2()`](https://www.sqlite.org/c3ref/close.html). * @since v22.5.0 */ close(): void; + /** + * Loads a shared library into the database connection. This method is a wrapper + * around [`sqlite3_load_extension()`](https://www.sqlite.org/c3ref/load_extension.html). It is required to enable the + * `allowExtension` option when constructing the `DatabaseSync` instance. + * @since v22.13.0 + * @param path The path to the shared library to load. + */ + loadExtension(path: string): void; + /** + * Enables or disables the `loadExtension` SQL function, and the `loadExtension()` + * method. When `allowExtension` is `false` when constructing, you cannot enable + * loading extensions for security reasons. + * @since v22.13.0 + * @param allow Whether to allow loading extensions. + */ + enableLoadExtension(allow: boolean): void; + /** + * This method is a wrapper around [`sqlite3_db_filename()`](https://sqlite.org/c3ref/db_filename.html) + * @since v22.16.0 + * @param dbName Name of the database. This can be `'main'` (the default primary database) or any other + * database that has been added with [`ATTACH DATABASE`](https://www.sqlite.org/lang_attach.html) **Default:** `'main'`. + * @returns The location of the database file. When using an in-memory database, + * this method returns null. + */ + location(dbName?: string): string | null; /** * This method allows one or more SQL statements to be executed without returning * any results. This method is useful when executing SQL statements read from a @@ -80,7 +278,36 @@ declare module "node:sqlite" { */ exec(sql: string): void; /** - * Opens the database specified in the `location` argument of the `DatabaseSync`constructor. This method should only be used when the database is not opened via + * This method is used to create SQLite user-defined functions. This method is a + * wrapper around [`sqlite3_create_function_v2()`](https://www.sqlite.org/c3ref/create_function.html). + * @since v22.13.0 + * @param name The name of the SQLite function to create. + * @param options Optional configuration settings for the function. + * @param func The JavaScript function to call when the SQLite + * function is invoked. The return value of this function should be a valid + * SQLite data type: see + * [Type conversion between JavaScript and SQLite](https://nodejs.org/docs/latest-v22.x/api/sqlite.html#type-conversion-between-javascript-and-sqlite). + * The result defaults to `NULL` if the return value is `undefined`. + */ + function( + name: string, + options: FunctionOptions, + func: (...args: SQLOutputValue[]) => SQLInputValue, + ): void; + function(name: string, func: (...args: SQLOutputValue[]) => SQLInputValue): void; + /** + * Whether the database is currently open or not. + * @since v22.15.0 + */ + readonly isOpen: boolean; + /** + * Whether the database is currently within a transaction. This method + * is a wrapper around [`sqlite3_get_autocommit()`](https://sqlite.org/c3ref/get_autocommit.html). + * @since v22.16.0 + */ + readonly isTransaction: boolean; + /** + * Opens the database specified in the `path` argument of the `DatabaseSync`constructor. This method should only be used when the database is not opened via * the constructor. An exception is thrown if the database is already open. * @since v22.5.0 */ @@ -93,8 +320,112 @@ declare module "node:sqlite" { * @return The prepared statement. */ prepare(sql: string): StatementSync; + /** + * Creates and attaches a session to the database. This method is a wrapper around + * [`sqlite3session_create()`](https://www.sqlite.org/session/sqlite3session_create.html) and + * [`sqlite3session_attach()`](https://www.sqlite.org/session/sqlite3session_attach.html). + * @param options The configuration options for the session. + * @returns A session handle. + * @since v22.12.0 + */ + createSession(options?: CreateSessionOptions): Session; + /** + * An exception is thrown if the database is not + * open. This method is a wrapper around + * [`sqlite3changeset_apply()`](https://www.sqlite.org/session/sqlite3changeset_apply.html). + * + * ```js + * const sourceDb = new DatabaseSync(':memory:'); + * const targetDb = new DatabaseSync(':memory:'); + * + * sourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)'); + * targetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)'); + * + * const session = sourceDb.createSession(); + * + * const insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)'); + * insert.run(1, 'hello'); + * insert.run(2, 'world'); + * + * const changeset = session.changeset(); + * targetDb.applyChangeset(changeset); + * // Now that the changeset has been applied, targetDb contains the same data as sourceDb. + * ``` + * @param changeset A binary changeset or patchset. + * @param options The configuration options for how the changes will be applied. + * @returns Whether the changeset was applied successfully without being aborted. + * @since v22.12.0 + */ + applyChangeset(changeset: Uint8Array, options?: ApplyChangesetOptions): boolean; + /** + * Closes the database connection. If the database connection is already closed + * then this is a no-op. + * @since v22.15.0 + * @experimental + */ + [Symbol.dispose](): void; + } + /** + * @since v22.12.0 + */ + interface Session { + /** + * Retrieves a changeset containing all changes since the changeset was created. Can be called multiple times. + * An exception is thrown if the database or the session is not open. This method is a wrapper around + * [`sqlite3session_changeset()`](https://www.sqlite.org/session/sqlite3session_changeset.html). + * @returns Binary changeset that can be applied to other databases. + * @since v22.12.0 + */ + changeset(): Uint8Array; + /** + * Similar to the method above, but generates a more compact patchset. See + * [Changesets and Patchsets](https://www.sqlite.org/sessionintro.html#changesets_and_patchsets) + * in the documentation of SQLite. An exception is thrown if the database or the session is not open. This method is a + * wrapper around + * [`sqlite3session_patchset()`](https://www.sqlite.org/session/sqlite3session_patchset.html). + * @returns Binary patchset that can be applied to other databases. + * @since v22.12.0 + */ + patchset(): Uint8Array; + /** + * Closes the session. An exception is thrown if the database or the session is not open. This method is a + * wrapper around + * [`sqlite3session_delete()`](https://www.sqlite.org/session/sqlite3session_delete.html). + */ + close(): void; + } + interface StatementColumnMetadata { + /** + * The unaliased name of the column in the origin + * table, or `null` if the column is the result of an expression or subquery. + * This property is the result of [`sqlite3_column_origin_name()`](https://www.sqlite.org/c3ref/column_database_name.html). + */ + column: string | null; + /** + * The unaliased name of the origin database, or + * `null` if the column is the result of an expression or subquery. This + * property is the result of [`sqlite3_column_database_name()`](https://www.sqlite.org/c3ref/column_database_name.html). + */ + database: string | null; + /** + * The name assigned to the column in the result set of a + * `SELECT` statement. This property is the result of + * [`sqlite3_column_name()`](https://www.sqlite.org/c3ref/column_name.html). + */ + name: string; + /** + * The unaliased name of the origin table, or `null` if + * the column is the result of an expression or subquery. This property is the + * result of [`sqlite3_column_table_name()`](https://www.sqlite.org/c3ref/column_database_name.html). + */ + table: string | null; + /** + * The declared data type of the column, or `null` if the + * column is the result of an expression or subquery. This property is the + * result of [`sqlite3_column_decltype()`](https://www.sqlite.org/c3ref/column_decltype.html). + */ + type: string | null; } - type SupportedValueType = null | number | bigint | string | Uint8Array; interface StatementResultingChanges { /** * The number of rows modified, inserted, or deleted by the most recently completed `INSERT`, `UPDATE`, or `DELETE` statement. @@ -134,18 +465,27 @@ declare module "node:sqlite" { * @return An array of objects. Each object corresponds to a row returned by executing the prepared statement. The keys and values of each object correspond to the column names and values of * the row. */ - all(...anonymousParameters: SupportedValueType[]): unknown[]; + all(...anonymousParameters: SQLInputValue[]): Record[]; all( - namedParameters: Record, - ...anonymousParameters: SupportedValueType[] - ): unknown[]; + namedParameters: Record, + ...anonymousParameters: SQLInputValue[] + ): Record[]; /** - * This method returns the source SQL of the prepared statement with parameter - * placeholders replaced by values. This method is a wrapper around [`sqlite3_expanded_sql()`](https://www.sqlite.org/c3ref/expanded_sql.html). + * This method is used to retrieve information about the columns returned by the + * prepared statement. + * @since v22.16.0 + * @returns An array of objects. Each object corresponds to a column + * in the prepared statement, and contains the following properties: + */ + columns(): StatementColumnMetadata[]; + /** + * The source SQL text of the prepared statement with parameter + * placeholders replaced by the values that were used during the most recent + * execution of this prepared statement. This property is a wrapper around + * [`sqlite3_expanded_sql()`](https://www.sqlite.org/c3ref/expanded_sql.html). * @since v22.5.0 - * @return The source SQL expanded to include parameter values. */ - expandedSQL(): string; + readonly expandedSQL: string; /** * This method executes a prepared statement and returns the first result as an * object. If the prepared statement does not return any results, this method @@ -157,8 +497,29 @@ declare module "node:sqlite" { * @return An object corresponding to the first row returned by executing the prepared statement. The keys and values of the object correspond to the column names and values of the row. If no * rows were returned from the database then this method returns `undefined`. */ - get(...anonymousParameters: SupportedValueType[]): unknown; - get(namedParameters: Record, ...anonymousParameters: SupportedValueType[]): unknown; + get(...anonymousParameters: SQLInputValue[]): Record | undefined; + get( + namedParameters: Record, + ...anonymousParameters: SQLInputValue[] + ): Record | undefined; + /** + * This method executes a prepared statement and returns an iterator of + * objects. If the prepared statement does not return any results, this method + * returns an empty iterator. The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_blob.html) using + * the values in `namedParameters` and `anonymousParameters`. + * @since v22.13.0 + * @param namedParameters An optional object used to bind named parameters. + * The keys of this object are used to configure the mapping. + * @param anonymousParameters Zero or more values to bind to anonymous parameters. + * @returns An iterable iterator of objects. Each object corresponds to a row + * returned by executing the prepared statement. The keys and values of each + * object correspond to the column names and values of the row. + */ + iterate(...anonymousParameters: SQLInputValue[]): NodeJS.Iterator>; + iterate( + namedParameters: Record, + ...anonymousParameters: SQLInputValue[] + ): NodeJS.Iterator>; /** * This method executes a prepared statement and returns an object summarizing the * resulting changes. The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_blob.html) using the @@ -167,10 +528,10 @@ declare module "node:sqlite" { * @param namedParameters An optional object used to bind named parameters. The keys of this object are used to configure the mapping. * @param anonymousParameters Zero or more values to bind to anonymous parameters. */ - run(...anonymousParameters: SupportedValueType[]): StatementResultingChanges; + run(...anonymousParameters: SQLInputValue[]): StatementResultingChanges; run( - namedParameters: Record, - ...anonymousParameters: SupportedValueType[] + namedParameters: Record, + ...anonymousParameters: SQLInputValue[] ): StatementResultingChanges; /** * The names of SQLite parameters begin with a prefix character. By default,`node:sqlite` requires that this prefix character is present when binding @@ -191,6 +552,13 @@ declare module "node:sqlite" { * @param enabled Enables or disables support for binding named parameters without the prefix character. */ setAllowBareNamedParameters(enabled: boolean): void; + /** + * By default, if an unknown name is encountered while binding parameters, an + * exception is thrown. This method allows unknown named parameters to be ignored. + * @since v22.15.0 + * @param enabled Enables or disables support for unknown named parameters. + */ + setAllowUnknownNamedParameters(enabled: boolean): void; /** * When reading from the database, SQLite `INTEGER`s are mapped to JavaScript * numbers by default. However, SQLite `INTEGER`s can store values larger than @@ -203,11 +571,110 @@ declare module "node:sqlite" { */ setReadBigInts(enabled: boolean): void; /** - * This method returns the source SQL of the prepared statement. This method is a + * The source SQL text of the prepared statement. This property is a * wrapper around [`sqlite3_sql()`](https://www.sqlite.org/c3ref/expanded_sql.html). * @since v22.5.0 - * @return The source SQL used to create this prepared statement. */ - sourceSQL(): string; + readonly sourceSQL: string; + } + interface BackupOptions { + /** + * Name of the source database. This can be `'main'` (the default primary database) or any other + * database that have been added with [`ATTACH DATABASE`](https://www.sqlite.org/lang_attach.html) + * @default 'main' + */ + source?: string | undefined; + /** + * Name of the target database. This can be `'main'` (the default primary database) or any other + * database that have been added with [`ATTACH DATABASE`](https://www.sqlite.org/lang_attach.html) + * @default 'main' + */ + target?: string | undefined; + /** + * Number of pages to be transmitted in each batch of the backup. + * @default 100 + */ + rate?: number | undefined; + /** + * Callback function that will be called with the number of pages copied and the total number of + * pages. + */ + progress?: ((progressInfo: BackupProgressInfo) => void) | undefined; + } + interface BackupProgressInfo { + totalPages: number; + remainingPages: number; + } + /** + * This method makes a database backup. This method abstracts the + * [`sqlite3_backup_init()`](https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit), + * [`sqlite3_backup_step()`](https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep) + * and [`sqlite3_backup_finish()`](https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish) functions. + * + * The backed-up database can be used normally during the backup process. Mutations coming from the same connection - same + * `DatabaseSync` - object will be reflected in the backup right away. However, mutations from other connections will cause + * the backup process to restart. + * + * ```js + * import { backup, DatabaseSync } from 'node:sqlite'; + * + * const sourceDb = new DatabaseSync('source.db'); + * const totalPagesTransferred = await backup(sourceDb, 'backup.db', { + * rate: 1, // Copy one page at a time. + * progress: ({ totalPages, remainingPages }) => { + * console.log('Backup in progress', { totalPages, remainingPages }); + * }, + * }); + * + * console.log('Backup completed', totalPagesTransferred); + * ``` + * @since v22.16.0 + * @param sourceDb The database to backup. The source database must be open. + * @param path The path where the backup will be created. If the file already exists, + * the contents will be overwritten. + * @param options Optional configuration for the backup. The + * following properties are supported: + * @returns A promise that resolves when the backup is completed and rejects if an error occurs. + */ + function backup(sourceDb: DatabaseSync, path: string | Buffer | URL, options?: BackupOptions): Promise; + /** + * @since v22.13.0 + */ + namespace constants { + /** + * The conflict handler is invoked with this constant when processing a DELETE or UPDATE change if a row with the required PRIMARY KEY fields is present in the database, but one or more other (non primary-key) fields modified by the update do not contain the expected "before" values. + * @since v22.14.0 + */ + const SQLITE_CHANGESET_DATA: number; + /** + * The conflict handler is invoked with this constant when processing a DELETE or UPDATE change if a row with the required PRIMARY KEY fields is not present in the database. + * @since v22.14.0 + */ + const SQLITE_CHANGESET_NOTFOUND: number; + /** + * This constant is passed to the conflict handler while processing an INSERT change if the operation would result in duplicate primary key values. + * @since v22.14.0 + */ + const SQLITE_CHANGESET_CONFLICT: number; + /** + * If foreign key handling is enabled, and applying a changeset leaves the database in a state containing foreign key violations, the conflict handler is invoked with this constant exactly once before the changeset is committed. If the conflict handler returns `SQLITE_CHANGESET_OMIT`, the changes, including those that caused the foreign key constraint violation, are committed. Or, if it returns `SQLITE_CHANGESET_ABORT`, the changeset is rolled back. + * @since v22.14.0 + */ + const SQLITE_CHANGESET_FOREIGN_KEY: number; + /** + * Conflicting changes are omitted. + * @since v22.12.0 + */ + const SQLITE_CHANGESET_OMIT: number; + /** + * Conflicting changes replace existing values. Note that this value can only be returned when the type of conflict is either `SQLITE_CHANGESET_DATA` or `SQLITE_CHANGESET_CONFLICT`. + * @since v22.12.0 + */ + const SQLITE_CHANGESET_REPLACE: number; + /** + * Abort when a change encounters a conflict and roll back database. + * @since v22.12.0 + */ + const SQLITE_CHANGESET_ABORT: number; } } diff --git a/node_modules/@types/node/stream.d.ts b/node_modules/@types/node/stream.d.ts index 916bfcb03..278021748 100644 --- a/node_modules/@types/node/stream.d.ts +++ b/node_modules/@types/node/stream.d.ts @@ -21,12 +21,11 @@ declare module "stream" { import { Abortable, EventEmitter } from "node:events"; import { Blob as NodeBlob } from "node:buffer"; import * as streamPromises from "node:stream/promises"; - import * as streamConsumers from "node:stream/consumers"; import * as streamWeb from "node:stream/web"; type ComposeFnParam = (source: any) => void; - class internal extends EventEmitter { + class Stream extends EventEmitter { pipe( destination: T, options?: { @@ -38,919 +37,10 @@ declare module "stream" { options?: { signal: AbortSignal }, ): T; } - import Stream = internal.Stream; - import Readable = internal.Readable; - import ReadableOptions = internal.ReadableOptions; - interface ArrayOptions { - /** - * The maximum concurrent invocations of `fn` to call on the stream at once. - * @default 1 - */ - concurrency?: number; - /** Allows destroying the stream if the signal is aborted. */ - signal?: AbortSignal; - } - class ReadableBase extends Stream implements NodeJS.ReadableStream { - /** - * A utility method for creating Readable Streams out of iterators. - * @since v12.3.0, v10.17.0 - * @param iterable Object implementing the `Symbol.asyncIterator` or `Symbol.iterator` iterable protocol. Emits an 'error' event if a null value is passed. - * @param options Options provided to `new stream.Readable([options])`. By default, `Readable.from()` will set `options.objectMode` to `true`, unless this is explicitly opted out by setting `options.objectMode` to `false`. - */ - static from(iterable: Iterable | AsyncIterable, options?: ReadableOptions): Readable; - /** - * Returns whether the stream has been read from or cancelled. - * @since v16.8.0 - */ - static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean; - /** - * Returns whether the stream was destroyed or errored before emitting `'end'`. - * @since v16.8.0 - * @experimental - */ - readonly readableAborted: boolean; - /** - * Is `true` if it is safe to call {@link read}, which means - * the stream has not been destroyed or emitted `'error'` or `'end'`. - * @since v11.4.0 - */ - readable: boolean; - /** - * Returns whether `'data'` has been emitted. - * @since v16.7.0, v14.18.0 - * @experimental - */ - readonly readableDidRead: boolean; - /** - * Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the {@link setEncoding} method. - * @since v12.7.0 - */ - readonly readableEncoding: BufferEncoding | null; - /** - * Becomes `true` when [`'end'`](https://nodejs.org/docs/latest-v22.x/api/stream.html#event-end) event is emitted. - * @since v12.9.0 - */ - readonly readableEnded: boolean; - /** - * This property reflects the current state of a `Readable` stream as described - * in the [Three states](https://nodejs.org/docs/latest-v22.x/api/stream.html#three-states) section. - * @since v9.4.0 - */ - readonly readableFlowing: boolean | null; - /** - * Returns the value of `highWaterMark` passed when creating this `Readable`. - * @since v9.3.0 - */ - readonly readableHighWaterMark: number; - /** - * This property contains the number of bytes (or objects) in the queue - * ready to be read. The value provides introspection data regarding - * the status of the `highWaterMark`. - * @since v9.4.0 - */ - readonly readableLength: number; - /** - * Getter for the property `objectMode` of a given `Readable` stream. - * @since v12.3.0 - */ - readonly readableObjectMode: boolean; - /** - * Is `true` after `readable.destroy()` has been called. - * @since v8.0.0 - */ - destroyed: boolean; - /** - * Is `true` after `'close'` has been emitted. - * @since v18.0.0 - */ - readonly closed: boolean; - /** - * Returns error if the stream has been destroyed with an error. - * @since v18.0.0 - */ - readonly errored: Error | null; - constructor(opts?: ReadableOptions); - _construct?(callback: (error?: Error | null) => void): void; - _read(size: number): void; - /** - * The `readable.read()` method reads data out of the internal buffer and - * returns it. If no data is available to be read, `null` is returned. By default, - * the data is returned as a `Buffer` object unless an encoding has been - * specified using the `readable.setEncoding()` method or the stream is operating - * in object mode. - * - * The optional `size` argument specifies a specific number of bytes to read. If - * `size` bytes are not available to be read, `null` will be returned _unless_ the - * stream has ended, in which case all of the data remaining in the internal buffer - * will be returned. - * - * If the `size` argument is not specified, all of the data contained in the - * internal buffer will be returned. - * - * The `size` argument must be less than or equal to 1 GiB. - * - * The `readable.read()` method should only be called on `Readable` streams - * operating in paused mode. In flowing mode, `readable.read()` is called - * automatically until the internal buffer is fully drained. - * - * ```js - * const readable = getReadableStreamSomehow(); - * - * // 'readable' may be triggered multiple times as data is buffered in - * readable.on('readable', () => { - * let chunk; - * console.log('Stream is readable (new data received in buffer)'); - * // Use a loop to make sure we read all currently available data - * while (null !== (chunk = readable.read())) { - * console.log(`Read ${chunk.length} bytes of data...`); - * } - * }); - * - * // 'end' will be triggered once when there is no more data available - * readable.on('end', () => { - * console.log('Reached end of stream.'); - * }); - * ``` - * - * Each call to `readable.read()` returns a chunk of data, or `null`. The chunks - * are not concatenated. A `while` loop is necessary to consume all data - * currently in the buffer. When reading a large file `.read()` may return `null`, - * having consumed all buffered content so far, but there is still more data to - * come not yet buffered. In this case a new `'readable'` event will be emitted - * when there is more data in the buffer. Finally the `'end'` event will be - * emitted when there is no more data to come. - * - * Therefore to read a file's whole contents from a `readable`, it is necessary - * to collect chunks across multiple `'readable'` events: - * - * ```js - * const chunks = []; - * - * readable.on('readable', () => { - * let chunk; - * while (null !== (chunk = readable.read())) { - * chunks.push(chunk); - * } - * }); - * - * readable.on('end', () => { - * const content = chunks.join(''); - * }); - * ``` - * - * A `Readable` stream in object mode will always return a single item from - * a call to `readable.read(size)`, regardless of the value of the `size` argument. - * - * If the `readable.read()` method returns a chunk of data, a `'data'` event will - * also be emitted. - * - * Calling {@link read} after the `'end'` event has - * been emitted will return `null`. No runtime error will be raised. - * @since v0.9.4 - * @param size Optional argument to specify how much data to read. - */ - read(size?: number): any; - /** - * The `readable.setEncoding()` method sets the character encoding for - * data read from the `Readable` stream. - * - * By default, no encoding is assigned and stream data will be returned as `Buffer` objects. Setting an encoding causes the stream data - * to be returned as strings of the specified encoding rather than as `Buffer` objects. For instance, calling `readable.setEncoding('utf8')` will cause the - * output data to be interpreted as UTF-8 data, and passed as strings. Calling `readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal - * string format. - * - * The `Readable` stream will properly handle multi-byte characters delivered - * through the stream that would otherwise become improperly decoded if simply - * pulled from the stream as `Buffer` objects. - * - * ```js - * const readable = getReadableStreamSomehow(); - * readable.setEncoding('utf8'); - * readable.on('data', (chunk) => { - * assert.equal(typeof chunk, 'string'); - * console.log('Got %d characters of string data:', chunk.length); - * }); - * ``` - * @since v0.9.4 - * @param encoding The encoding to use. - */ - setEncoding(encoding: BufferEncoding): this; - /** - * The `readable.pause()` method will cause a stream in flowing mode to stop - * emitting `'data'` events, switching out of flowing mode. Any data that - * becomes available will remain in the internal buffer. - * - * ```js - * const readable = getReadableStreamSomehow(); - * readable.on('data', (chunk) => { - * console.log(`Received ${chunk.length} bytes of data.`); - * readable.pause(); - * console.log('There will be no additional data for 1 second.'); - * setTimeout(() => { - * console.log('Now data will start flowing again.'); - * readable.resume(); - * }, 1000); - * }); - * ``` - * - * The `readable.pause()` method has no effect if there is a `'readable'` event listener. - * @since v0.9.4 - */ - pause(): this; - /** - * The `readable.resume()` method causes an explicitly paused `Readable` stream to - * resume emitting `'data'` events, switching the stream into flowing mode. - * - * The `readable.resume()` method can be used to fully consume the data from a - * stream without actually processing any of that data: - * - * ```js - * getReadableStreamSomehow() - * .resume() - * .on('end', () => { - * console.log('Reached the end, but did not read anything.'); - * }); - * ``` - * - * The `readable.resume()` method has no effect if there is a `'readable'` event listener. - * @since v0.9.4 - */ - resume(): this; - /** - * The `readable.isPaused()` method returns the current operating state of the `Readable`. - * This is used primarily by the mechanism that underlies the `readable.pipe()` method. - * In most typical cases, there will be no reason to use this method directly. - * - * ```js - * const readable = new stream.Readable(); - * - * readable.isPaused(); // === false - * readable.pause(); - * readable.isPaused(); // === true - * readable.resume(); - * readable.isPaused(); // === false - * ``` - * @since v0.11.14 - */ - isPaused(): boolean; - /** - * The `readable.unpipe()` method detaches a `Writable` stream previously attached - * using the {@link pipe} method. - * - * If the `destination` is not specified, then _all_ pipes are detached. - * - * If the `destination` is specified, but no pipe is set up for it, then - * the method does nothing. - * - * ```js - * import fs from 'node:fs'; - * const readable = getReadableStreamSomehow(); - * const writable = fs.createWriteStream('file.txt'); - * // All the data from readable goes into 'file.txt', - * // but only for the first second. - * readable.pipe(writable); - * setTimeout(() => { - * console.log('Stop writing to file.txt.'); - * readable.unpipe(writable); - * console.log('Manually close the file stream.'); - * writable.end(); - * }, 1000); - * ``` - * @since v0.9.4 - * @param destination Optional specific stream to unpipe - */ - unpipe(destination?: NodeJS.WritableStream): this; - /** - * Passing `chunk` as `null` signals the end of the stream (EOF) and behaves the - * same as `readable.push(null)`, after which no more data can be written. The EOF - * signal is put at the end of the buffer and any buffered data will still be - * flushed. - * - * The `readable.unshift()` method pushes a chunk of data back into the internal - * buffer. This is useful in certain situations where a stream is being consumed by - * code that needs to "un-consume" some amount of data that it has optimistically - * pulled out of the source, so that the data can be passed on to some other party. - * - * The `stream.unshift(chunk)` method cannot be called after the `'end'` event - * has been emitted or a runtime error will be thrown. - * - * Developers using `stream.unshift()` often should consider switching to - * use of a `Transform` stream instead. See the `API for stream implementers` section for more information. - * - * ```js - * // Pull off a header delimited by \n\n. - * // Use unshift() if we get too much. - * // Call the callback with (error, header, stream). - * import { StringDecoder } from 'node:string_decoder'; - * function parseHeader(stream, callback) { - * stream.on('error', callback); - * stream.on('readable', onReadable); - * const decoder = new StringDecoder('utf8'); - * let header = ''; - * function onReadable() { - * let chunk; - * while (null !== (chunk = stream.read())) { - * const str = decoder.write(chunk); - * if (str.includes('\n\n')) { - * // Found the header boundary. - * const split = str.split(/\n\n/); - * header += split.shift(); - * const remaining = split.join('\n\n'); - * const buf = Buffer.from(remaining, 'utf8'); - * stream.removeListener('error', callback); - * // Remove the 'readable' listener before unshifting. - * stream.removeListener('readable', onReadable); - * if (buf.length) - * stream.unshift(buf); - * // Now the body of the message can be read from the stream. - * callback(null, header, stream); - * return; - * } - * // Still reading the header. - * header += str; - * } - * } - * } - * ``` - * - * Unlike {@link push}, `stream.unshift(chunk)` will not - * end the reading process by resetting the internal reading state of the stream. - * This can cause unexpected results if `readable.unshift()` is called during a - * read (i.e. from within a {@link _read} implementation on a - * custom stream). Following the call to `readable.unshift()` with an immediate {@link push} will reset the reading state appropriately, - * however it is best to simply avoid calling `readable.unshift()` while in the - * process of performing a read. - * @since v0.9.11 - * @param chunk Chunk of data to unshift onto the read queue. For streams not operating in object mode, `chunk` must - * be a {string}, {Buffer}, {TypedArray}, {DataView} or `null`. For object mode streams, `chunk` may be any JavaScript value. - * @param encoding Encoding of string chunks. Must be a valid `Buffer` encoding, such as `'utf8'` or `'ascii'`. - */ - unshift(chunk: any, encoding?: BufferEncoding): void; - /** - * Prior to Node.js 0.10, streams did not implement the entire `node:stream` module API as it is currently defined. (See `Compatibility` for more - * information.) - * - * When using an older Node.js library that emits `'data'` events and has a {@link pause} method that is advisory only, the `readable.wrap()` method can be used to create a `Readable` - * stream that uses - * the old stream as its data source. - * - * It will rarely be necessary to use `readable.wrap()` but the method has been - * provided as a convenience for interacting with older Node.js applications and - * libraries. - * - * ```js - * import { OldReader } from './old-api-module.js'; - * import { Readable } from 'node:stream'; - * const oreader = new OldReader(); - * const myReader = new Readable().wrap(oreader); - * - * myReader.on('readable', () => { - * myReader.read(); // etc. - * }); - * ``` - * @since v0.9.4 - * @param stream An "old style" readable stream - */ - wrap(stream: NodeJS.ReadableStream): this; - push(chunk: any, encoding?: BufferEncoding): boolean; - /** - * The iterator created by this method gives users the option to cancel the destruction - * of the stream if the `for await...of` loop is exited by `return`, `break`, or `throw`, - * or if the iterator should destroy the stream if the stream emitted an error during iteration. - * @since v16.3.0 - * @param options.destroyOnReturn When set to `false`, calling `return` on the async iterator, - * or exiting a `for await...of` iteration using a `break`, `return`, or `throw` will not destroy the stream. - * **Default: `true`**. - */ - iterator(options?: { destroyOnReturn?: boolean }): NodeJS.AsyncIterator; - /** - * This method allows mapping over the stream. The *fn* function will be called for every chunk in the stream. - * If the *fn* function returns a promise - that promise will be `await`ed before being passed to the result stream. - * @since v17.4.0, v16.14.0 - * @param fn a function to map over every chunk in the stream. Async or not. - * @returns a stream mapped with the function *fn*. - */ - map(fn: (data: any, options?: Pick) => any, options?: ArrayOptions): Readable; - /** - * This method allows filtering the stream. For each chunk in the stream the *fn* function will be called - * and if it returns a truthy value, the chunk will be passed to the result stream. - * If the *fn* function returns a promise - that promise will be `await`ed. - * @since v17.4.0, v16.14.0 - * @param fn a function to filter chunks from the stream. Async or not. - * @returns a stream filtered with the predicate *fn*. - */ - filter( - fn: (data: any, options?: Pick) => boolean | Promise, - options?: ArrayOptions, - ): Readable; - /** - * This method allows iterating a stream. For each chunk in the stream the *fn* function will be called. - * If the *fn* function returns a promise - that promise will be `await`ed. - * - * This method is different from `for await...of` loops in that it can optionally process chunks concurrently. - * In addition, a `forEach` iteration can only be stopped by having passed a `signal` option - * and aborting the related AbortController while `for await...of` can be stopped with `break` or `return`. - * In either case the stream will be destroyed. - * - * This method is different from listening to the `'data'` event in that it uses the `readable` event - * in the underlying machinary and can limit the number of concurrent *fn* calls. - * @since v17.5.0 - * @param fn a function to call on each chunk of the stream. Async or not. - * @returns a promise for when the stream has finished. - */ - forEach( - fn: (data: any, options?: Pick) => void | Promise, - options?: ArrayOptions, - ): Promise; - /** - * This method allows easily obtaining the contents of a stream. - * - * As this method reads the entire stream into memory, it negates the benefits of streams. It's intended - * for interoperability and convenience, not as the primary way to consume streams. - * @since v17.5.0 - * @returns a promise containing an array with the contents of the stream. - */ - toArray(options?: Pick): Promise; - /** - * This method is similar to `Array.prototype.some` and calls *fn* on each chunk in the stream - * until the awaited return value is `true` (or any truthy value). Once an *fn* call on a chunk - * `await`ed return value is truthy, the stream is destroyed and the promise is fulfilled with `true`. - * If none of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `false`. - * @since v17.5.0 - * @param fn a function to call on each chunk of the stream. Async or not. - * @returns a promise evaluating to `true` if *fn* returned a truthy value for at least one of the chunks. - */ - some( - fn: (data: any, options?: Pick) => boolean | Promise, - options?: ArrayOptions, - ): Promise; - /** - * This method is similar to `Array.prototype.find` and calls *fn* on each chunk in the stream - * to find a chunk with a truthy value for *fn*. Once an *fn* call's awaited return value is truthy, - * the stream is destroyed and the promise is fulfilled with value for which *fn* returned a truthy value. - * If all of the *fn* calls on the chunks return a falsy value, the promise is fulfilled with `undefined`. - * @since v17.5.0 - * @param fn a function to call on each chunk of the stream. Async or not. - * @returns a promise evaluating to the first chunk for which *fn* evaluated with a truthy value, - * or `undefined` if no element was found. - */ - find( - fn: (data: any, options?: Pick) => data is T, - options?: ArrayOptions, - ): Promise; - find( - fn: (data: any, options?: Pick) => boolean | Promise, - options?: ArrayOptions, - ): Promise; - /** - * This method is similar to `Array.prototype.every` and calls *fn* on each chunk in the stream - * to check if all awaited return values are truthy value for *fn*. Once an *fn* call on a chunk - * `await`ed return value is falsy, the stream is destroyed and the promise is fulfilled with `false`. - * If all of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `true`. - * @since v17.5.0 - * @param fn a function to call on each chunk of the stream. Async or not. - * @returns a promise evaluating to `true` if *fn* returned a truthy value for every one of the chunks. - */ - every( - fn: (data: any, options?: Pick) => boolean | Promise, - options?: ArrayOptions, - ): Promise; - /** - * This method returns a new stream by applying the given callback to each chunk of the stream - * and then flattening the result. - * - * It is possible to return a stream or another iterable or async iterable from *fn* and the result streams - * will be merged (flattened) into the returned stream. - * @since v17.5.0 - * @param fn a function to map over every chunk in the stream. May be async. May be a stream or generator. - * @returns a stream flat-mapped with the function *fn*. - */ - flatMap(fn: (data: any, options?: Pick) => any, options?: ArrayOptions): Readable; - /** - * This method returns a new stream with the first *limit* chunks dropped from the start. - * @since v17.5.0 - * @param limit the number of chunks to drop from the readable. - * @returns a stream with *limit* chunks dropped from the start. - */ - drop(limit: number, options?: Pick): Readable; - /** - * This method returns a new stream with the first *limit* chunks. - * @since v17.5.0 - * @param limit the number of chunks to take from the readable. - * @returns a stream with *limit* chunks taken. - */ - take(limit: number, options?: Pick): Readable; - /** - * This method returns a new stream with chunks of the underlying stream paired with a counter - * in the form `[index, chunk]`. The first index value is `0` and it increases by 1 for each chunk produced. - * @since v17.5.0 - * @returns a stream of indexed pairs. - */ - asIndexedPairs(options?: Pick): Readable; - /** - * This method calls *fn* on each chunk of the stream in order, passing it the result from the calculation - * on the previous element. It returns a promise for the final value of the reduction. - * - * If no *initial* value is supplied the first chunk of the stream is used as the initial value. - * If the stream is empty, the promise is rejected with a `TypeError` with the `ERR_INVALID_ARGS` code property. - * - * The reducer function iterates the stream element-by-element which means that there is no *concurrency* parameter - * or parallelism. To perform a reduce concurrently, you can extract the async function to `readable.map` method. - * @since v17.5.0 - * @param fn a reducer function to call over every chunk in the stream. Async or not. - * @param initial the initial value to use in the reduction. - * @returns a promise for the final value of the reduction. - */ - reduce( - fn: (previous: any, data: any, options?: Pick) => T, - initial?: undefined, - options?: Pick, - ): Promise; - reduce( - fn: (previous: T, data: any, options?: Pick) => T, - initial: T, - options?: Pick, - ): Promise; - _destroy(error: Error | null, callback: (error?: Error | null) => void): void; - /** - * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the readable - * stream will release any internal resources and subsequent calls to `push()` will be ignored. - * - * Once `destroy()` has been called any further calls will be a no-op and no - * further errors except from `_destroy()` may be emitted as `'error'`. - * - * Implementors should not override this method, but instead implement `readable._destroy()`. - * @since v8.0.0 - * @param error Error which will be passed as payload in `'error'` event - */ - destroy(error?: Error): this; - /** - * Event emitter - * The defined events on documents including: - * 1. close - * 2. data - * 3. end - * 4. error - * 5. pause - * 6. readable - * 7. resume - */ - addListener(event: "close", listener: () => void): this; - addListener(event: "data", listener: (chunk: any) => void): this; - addListener(event: "end", listener: () => void): this; - addListener(event: "error", listener: (err: Error) => void): this; - addListener(event: "pause", listener: () => void): this; - addListener(event: "readable", listener: () => void): this; - addListener(event: "resume", listener: () => void): this; - addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: "close"): boolean; - emit(event: "data", chunk: any): boolean; - emit(event: "end"): boolean; - emit(event: "error", err: Error): boolean; - emit(event: "pause"): boolean; - emit(event: "readable"): boolean; - emit(event: "resume"): boolean; - emit(event: string | symbol, ...args: any[]): boolean; - on(event: "close", listener: () => void): this; - on(event: "data", listener: (chunk: any) => void): this; - on(event: "end", listener: () => void): this; - on(event: "error", listener: (err: Error) => void): this; - on(event: "pause", listener: () => void): this; - on(event: "readable", listener: () => void): this; - on(event: "resume", listener: () => void): this; - on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: "close", listener: () => void): this; - once(event: "data", listener: (chunk: any) => void): this; - once(event: "end", listener: () => void): this; - once(event: "error", listener: (err: Error) => void): this; - once(event: "pause", listener: () => void): this; - once(event: "readable", listener: () => void): this; - once(event: "resume", listener: () => void): this; - once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: "close", listener: () => void): this; - prependListener(event: "data", listener: (chunk: any) => void): this; - prependListener(event: "end", listener: () => void): this; - prependListener(event: "error", listener: (err: Error) => void): this; - prependListener(event: "pause", listener: () => void): this; - prependListener(event: "readable", listener: () => void): this; - prependListener(event: "resume", listener: () => void): this; - prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: "close", listener: () => void): this; - prependOnceListener(event: "data", listener: (chunk: any) => void): this; - prependOnceListener(event: "end", listener: () => void): this; - prependOnceListener(event: "error", listener: (err: Error) => void): this; - prependOnceListener(event: "pause", listener: () => void): this; - prependOnceListener(event: "readable", listener: () => void): this; - prependOnceListener(event: "resume", listener: () => void): this; - prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: "close", listener: () => void): this; - removeListener(event: "data", listener: (chunk: any) => void): this; - removeListener(event: "end", listener: () => void): this; - removeListener(event: "error", listener: (err: Error) => void): this; - removeListener(event: "pause", listener: () => void): this; - removeListener(event: "readable", listener: () => void): this; - removeListener(event: "resume", listener: () => void): this; - removeListener(event: string | symbol, listener: (...args: any[]) => void): this; - [Symbol.asyncIterator](): NodeJS.AsyncIterator; - /** - * Calls `readable.destroy()` with an `AbortError` and returns a promise that fulfills when the stream is finished. - * @since v20.4.0 - */ - [Symbol.asyncDispose](): Promise; - } - import WritableOptions = internal.WritableOptions; - class WritableBase extends Stream implements NodeJS.WritableStream { - /** - * Is `true` if it is safe to call `writable.write()`, which means - * the stream has not been destroyed, errored, or ended. - * @since v11.4.0 - */ - readonly writable: boolean; - /** - * Is `true` after `writable.end()` has been called. This property - * does not indicate whether the data has been flushed, for this use `writable.writableFinished` instead. - * @since v12.9.0 - */ - readonly writableEnded: boolean; - /** - * Is set to `true` immediately before the `'finish'` event is emitted. - * @since v12.6.0 - */ - readonly writableFinished: boolean; - /** - * Return the value of `highWaterMark` passed when creating this `Writable`. - * @since v9.3.0 - */ - readonly writableHighWaterMark: number; - /** - * This property contains the number of bytes (or objects) in the queue - * ready to be written. The value provides introspection data regarding - * the status of the `highWaterMark`. - * @since v9.4.0 - */ - readonly writableLength: number; - /** - * Getter for the property `objectMode` of a given `Writable` stream. - * @since v12.3.0 - */ - readonly writableObjectMode: boolean; - /** - * Number of times `writable.uncork()` needs to be - * called in order to fully uncork the stream. - * @since v13.2.0, v12.16.0 - */ - readonly writableCorked: number; - /** - * Is `true` after `writable.destroy()` has been called. - * @since v8.0.0 - */ - destroyed: boolean; - /** - * Is `true` after `'close'` has been emitted. - * @since v18.0.0 - */ - readonly closed: boolean; - /** - * Returns error if the stream has been destroyed with an error. - * @since v18.0.0 - */ - readonly errored: Error | null; - /** - * Is `true` if the stream's buffer has been full and stream will emit `'drain'`. - * @since v15.2.0, v14.17.0 - */ - readonly writableNeedDrain: boolean; - constructor(opts?: WritableOptions); - _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; - _writev?( - chunks: Array<{ - chunk: any; - encoding: BufferEncoding; - }>, - callback: (error?: Error | null) => void, - ): void; - _construct?(callback: (error?: Error | null) => void): void; - _destroy(error: Error | null, callback: (error?: Error | null) => void): void; - _final(callback: (error?: Error | null) => void): void; - /** - * The `writable.write()` method writes some data to the stream, and calls the - * supplied `callback` once the data has been fully handled. If an error - * occurs, the `callback` will be called with the error as its - * first argument. The `callback` is called asynchronously and before `'error'` is - * emitted. - * - * The return value is `true` if the internal buffer is less than the `highWaterMark` configured when the stream was created after admitting `chunk`. - * If `false` is returned, further attempts to write data to the stream should - * stop until the `'drain'` event is emitted. - * - * While a stream is not draining, calls to `write()` will buffer `chunk`, and - * return false. Once all currently buffered chunks are drained (accepted for - * delivery by the operating system), the `'drain'` event will be emitted. - * Once `write()` returns false, do not write more chunks - * until the `'drain'` event is emitted. While calling `write()` on a stream that - * is not draining is allowed, Node.js will buffer all written chunks until - * maximum memory usage occurs, at which point it will abort unconditionally. - * Even before it aborts, high memory usage will cause poor garbage collector - * performance and high RSS (which is not typically released back to the system, - * even after the memory is no longer required). Since TCP sockets may never - * drain if the remote peer does not read the data, writing a socket that is - * not draining may lead to a remotely exploitable vulnerability. - * - * Writing data while the stream is not draining is particularly - * problematic for a `Transform`, because the `Transform` streams are paused - * by default until they are piped or a `'data'` or `'readable'` event handler - * is added. - * - * If the data to be written can be generated or fetched on demand, it is - * recommended to encapsulate the logic into a `Readable` and use {@link pipe}. However, if calling `write()` is preferred, it is - * possible to respect backpressure and avoid memory issues using the `'drain'` event: - * - * ```js - * function write(data, cb) { - * if (!stream.write(data)) { - * stream.once('drain', cb); - * } else { - * process.nextTick(cb); - * } - * } - * - * // Wait for cb to be called before doing any other write. - * write('hello', () => { - * console.log('Write completed, do more writes now.'); - * }); - * ``` - * - * A `Writable` stream in object mode will always ignore the `encoding` argument. - * @since v0.9.4 - * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer}, - * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`. - * @param [encoding='utf8'] The encoding, if `chunk` is a string. - * @param callback Callback for when this chunk of data is flushed. - * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean; - write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean; - /** - * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream. - * @since v0.11.15 - * @param encoding The new default encoding - */ - setDefaultEncoding(encoding: BufferEncoding): this; - /** - * Calling the `writable.end()` method signals that no more data will be written - * to the `Writable`. The optional `chunk` and `encoding` arguments allow one - * final additional chunk of data to be written immediately before closing the - * stream. - * - * Calling the {@link write} method after calling {@link end} will raise an error. - * - * ```js - * // Write 'hello, ' and then end with 'world!'. - * import fs from 'node:fs'; - * const file = fs.createWriteStream('example.txt'); - * file.write('hello, '); - * file.end('world!'); - * // Writing more now is not allowed! - * ``` - * @since v0.9.4 - * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer}, - * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`. - * @param encoding The encoding if `chunk` is a string - * @param callback Callback for when the stream is finished. - */ - end(cb?: () => void): this; - end(chunk: any, cb?: () => void): this; - end(chunk: any, encoding: BufferEncoding, cb?: () => void): this; - /** - * The `writable.cork()` method forces all written data to be buffered in memory. - * The buffered data will be flushed when either the {@link uncork} or {@link end} methods are called. - * - * The primary intent of `writable.cork()` is to accommodate a situation in which - * several small chunks are written to the stream in rapid succession. Instead of - * immediately forwarding them to the underlying destination, `writable.cork()` buffers all the chunks until `writable.uncork()` is called, which will pass them - * all to `writable._writev()`, if present. This prevents a head-of-line blocking - * situation where data is being buffered while waiting for the first small chunk - * to be processed. However, use of `writable.cork()` without implementing `writable._writev()` may have an adverse effect on throughput. - * - * See also: `writable.uncork()`, `writable._writev()`. - * @since v0.11.2 - */ - cork(): void; - /** - * The `writable.uncork()` method flushes all data buffered since {@link cork} was called. - * - * When using `writable.cork()` and `writable.uncork()` to manage the buffering - * of writes to a stream, defer calls to `writable.uncork()` using `process.nextTick()`. Doing so allows batching of all `writable.write()` calls that occur within a given Node.js event - * loop phase. - * - * ```js - * stream.cork(); - * stream.write('some '); - * stream.write('data '); - * process.nextTick(() => stream.uncork()); - * ``` - * - * If the `writable.cork()` method is called multiple times on a stream, the - * same number of calls to `writable.uncork()` must be called to flush the buffered - * data. - * - * ```js - * stream.cork(); - * stream.write('some '); - * stream.cork(); - * stream.write('data '); - * process.nextTick(() => { - * stream.uncork(); - * // The data will not be flushed until uncork() is called a second time. - * stream.uncork(); - * }); - * ``` - * - * See also: `writable.cork()`. - * @since v0.11.2 - */ - uncork(): void; - /** - * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the writable - * stream has ended and subsequent calls to `write()` or `end()` will result in - * an `ERR_STREAM_DESTROYED` error. - * This is a destructive and immediate way to destroy a stream. Previous calls to `write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error. - * Use `end()` instead of destroy if data should flush before close, or wait for - * the `'drain'` event before destroying the stream. - * - * Once `destroy()` has been called any further calls will be a no-op and no - * further errors except from `_destroy()` may be emitted as `'error'`. - * - * Implementors should not override this method, - * but instead implement `writable._destroy()`. - * @since v8.0.0 - * @param error Optional, an error to emit with `'error'` event. - */ - destroy(error?: Error): this; - /** - * Event emitter - * The defined events on documents including: - * 1. close - * 2. drain - * 3. error - * 4. finish - * 5. pipe - * 6. unpipe - */ - addListener(event: "close", listener: () => void): this; - addListener(event: "drain", listener: () => void): this; - addListener(event: "error", listener: (err: Error) => void): this; - addListener(event: "finish", listener: () => void): this; - addListener(event: "pipe", listener: (src: Readable) => void): this; - addListener(event: "unpipe", listener: (src: Readable) => void): this; - addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: "close"): boolean; - emit(event: "drain"): boolean; - emit(event: "error", err: Error): boolean; - emit(event: "finish"): boolean; - emit(event: "pipe", src: Readable): boolean; - emit(event: "unpipe", src: Readable): boolean; - emit(event: string | symbol, ...args: any[]): boolean; - on(event: "close", listener: () => void): this; - on(event: "drain", listener: () => void): this; - on(event: "error", listener: (err: Error) => void): this; - on(event: "finish", listener: () => void): this; - on(event: "pipe", listener: (src: Readable) => void): this; - on(event: "unpipe", listener: (src: Readable) => void): this; - on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: "close", listener: () => void): this; - once(event: "drain", listener: () => void): this; - once(event: "error", listener: (err: Error) => void): this; - once(event: "finish", listener: () => void): this; - once(event: "pipe", listener: (src: Readable) => void): this; - once(event: "unpipe", listener: (src: Readable) => void): this; - once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: "close", listener: () => void): this; - prependListener(event: "drain", listener: () => void): this; - prependListener(event: "error", listener: (err: Error) => void): this; - prependListener(event: "finish", listener: () => void): this; - prependListener(event: "pipe", listener: (src: Readable) => void): this; - prependListener(event: "unpipe", listener: (src: Readable) => void): this; - prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: "close", listener: () => void): this; - prependOnceListener(event: "drain", listener: () => void): this; - prependOnceListener(event: "error", listener: (err: Error) => void): this; - prependOnceListener(event: "finish", listener: () => void): this; - prependOnceListener(event: "pipe", listener: (src: Readable) => void): this; - prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this; - prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: "close", listener: () => void): this; - removeListener(event: "drain", listener: () => void): this; - removeListener(event: "error", listener: (err: Error) => void): this; - removeListener(event: "finish", listener: () => void): this; - removeListener(event: "pipe", listener: (src: Readable) => void): this; - removeListener(event: "unpipe", listener: (src: Readable) => void): this; - removeListener(event: string | symbol, listener: (...args: any[]) => void): this; + namespace Stream { + export { Stream, streamPromises as promises }; } - namespace internal { - class Stream extends internal { - constructor(opts?: ReadableOptions); - } + namespace Stream { interface StreamOptions extends Abortable { emitClose?: boolean | undefined; highWaterMark?: number | undefined; @@ -959,57 +49,672 @@ declare module "stream" { destroy?(this: T, error: Error | null, callback: (error?: Error | null) => void): void; autoDestroy?: boolean | undefined; } - interface ReadableOptions extends StreamOptions { + interface ReadableOptions extends StreamOptions { encoding?: BufferEncoding | undefined; - read?(this: Readable, size: number): void; + read?(this: T, size: number): void; + } + interface ArrayOptions { + /** + * The maximum concurrent invocations of `fn` to call on the stream at once. + * @default 1 + */ + concurrency?: number; + /** Allows destroying the stream if the signal is aborted. */ + signal?: AbortSignal; } /** * @since v0.9.4 */ - class Readable extends ReadableBase { + class Readable extends Stream implements NodeJS.ReadableStream { + /** + * A utility method for creating Readable Streams out of iterators. + * @since v12.3.0, v10.17.0 + * @param iterable Object implementing the `Symbol.asyncIterator` or `Symbol.iterator` iterable protocol. Emits an 'error' event if a null value is passed. + * @param options Options provided to `new stream.Readable([options])`. By default, `Readable.from()` will set `options.objectMode` to `true`, unless this is explicitly opted out by setting `options.objectMode` to `false`. + */ + static from(iterable: Iterable | AsyncIterable, options?: ReadableOptions): Readable; + /** + * A utility method for creating a `Readable` from a web `ReadableStream`. + * @since v17.0.0 + */ + static fromWeb( + readableStream: streamWeb.ReadableStream, + options?: Pick, + ): Readable; + /** + * A utility method for creating a web `ReadableStream` from a `Readable`. + * @since v17.0.0 + */ + static toWeb( + streamReadable: Readable, + options?: { + strategy?: streamWeb.QueuingStrategy | undefined; + }, + ): streamWeb.ReadableStream; + /** + * Returns whether the stream has been read from or cancelled. + * @since v16.8.0 + */ + static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean; + /** + * Returns whether the stream was destroyed or errored before emitting `'end'`. + * @since v16.8.0 + */ + readonly readableAborted: boolean; + /** + * Is `true` if it is safe to call {@link read}, which means + * the stream has not been destroyed or emitted `'error'` or `'end'`. + * @since v11.4.0 + */ + readable: boolean; + /** + * Returns whether `'data'` has been emitted. + * @since v16.7.0, v14.18.0 + */ + readonly readableDidRead: boolean; + /** + * Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the {@link setEncoding} method. + * @since v12.7.0 + */ + readonly readableEncoding: BufferEncoding | null; + /** + * Becomes `true` when [`'end'`](https://nodejs.org/docs/latest-v22.x/api/stream.html#event-end) event is emitted. + * @since v12.9.0 + */ + readonly readableEnded: boolean; + /** + * This property reflects the current state of a `Readable` stream as described + * in the [Three states](https://nodejs.org/docs/latest-v22.x/api/stream.html#three-states) section. + * @since v9.4.0 + */ + readonly readableFlowing: boolean | null; + /** + * Returns the value of `highWaterMark` passed when creating this `Readable`. + * @since v9.3.0 + */ + readonly readableHighWaterMark: number; + /** + * This property contains the number of bytes (or objects) in the queue + * ready to be read. The value provides introspection data regarding + * the status of the `highWaterMark`. + * @since v9.4.0 + */ + readonly readableLength: number; + /** + * Getter for the property `objectMode` of a given `Readable` stream. + * @since v12.3.0 + */ + readonly readableObjectMode: boolean; + /** + * Is `true` after `readable.destroy()` has been called. + * @since v8.0.0 + */ + destroyed: boolean; + /** + * Is `true` after `'close'` has been emitted. + * @since v18.0.0 + */ + readonly closed: boolean; + /** + * Returns error if the stream has been destroyed with an error. + * @since v18.0.0 + */ + readonly errored: Error | null; + constructor(opts?: ReadableOptions); + _construct?(callback: (error?: Error | null) => void): void; + _read(size: number): void; + /** + * The `readable.read()` method reads data out of the internal buffer and + * returns it. If no data is available to be read, `null` is returned. By default, + * the data is returned as a `Buffer` object unless an encoding has been + * specified using the `readable.setEncoding()` method or the stream is operating + * in object mode. + * + * The optional `size` argument specifies a specific number of bytes to read. If + * `size` bytes are not available to be read, `null` will be returned _unless_ the + * stream has ended, in which case all of the data remaining in the internal buffer + * will be returned. + * + * If the `size` argument is not specified, all of the data contained in the + * internal buffer will be returned. + * + * The `size` argument must be less than or equal to 1 GiB. + * + * The `readable.read()` method should only be called on `Readable` streams + * operating in paused mode. In flowing mode, `readable.read()` is called + * automatically until the internal buffer is fully drained. + * + * ```js + * const readable = getReadableStreamSomehow(); + * + * // 'readable' may be triggered multiple times as data is buffered in + * readable.on('readable', () => { + * let chunk; + * console.log('Stream is readable (new data received in buffer)'); + * // Use a loop to make sure we read all currently available data + * while (null !== (chunk = readable.read())) { + * console.log(`Read ${chunk.length} bytes of data...`); + * } + * }); + * + * // 'end' will be triggered once when there is no more data available + * readable.on('end', () => { + * console.log('Reached end of stream.'); + * }); + * ``` + * + * Each call to `readable.read()` returns a chunk of data, or `null`. The chunks + * are not concatenated. A `while` loop is necessary to consume all data + * currently in the buffer. When reading a large file `.read()` may return `null`, + * having consumed all buffered content so far, but there is still more data to + * come not yet buffered. In this case a new `'readable'` event will be emitted + * when there is more data in the buffer. Finally the `'end'` event will be + * emitted when there is no more data to come. + * + * Therefore to read a file's whole contents from a `readable`, it is necessary + * to collect chunks across multiple `'readable'` events: + * + * ```js + * const chunks = []; + * + * readable.on('readable', () => { + * let chunk; + * while (null !== (chunk = readable.read())) { + * chunks.push(chunk); + * } + * }); + * + * readable.on('end', () => { + * const content = chunks.join(''); + * }); + * ``` + * + * A `Readable` stream in object mode will always return a single item from + * a call to `readable.read(size)`, regardless of the value of the `size` argument. + * + * If the `readable.read()` method returns a chunk of data, a `'data'` event will + * also be emitted. + * + * Calling {@link read} after the `'end'` event has + * been emitted will return `null`. No runtime error will be raised. + * @since v0.9.4 + * @param size Optional argument to specify how much data to read. + */ + read(size?: number): any; + /** + * The `readable.setEncoding()` method sets the character encoding for + * data read from the `Readable` stream. + * + * By default, no encoding is assigned and stream data will be returned as `Buffer` objects. Setting an encoding causes the stream data + * to be returned as strings of the specified encoding rather than as `Buffer` objects. For instance, calling `readable.setEncoding('utf8')` will cause the + * output data to be interpreted as UTF-8 data, and passed as strings. Calling `readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal + * string format. + * + * The `Readable` stream will properly handle multi-byte characters delivered + * through the stream that would otherwise become improperly decoded if simply + * pulled from the stream as `Buffer` objects. + * + * ```js + * const readable = getReadableStreamSomehow(); + * readable.setEncoding('utf8'); + * readable.on('data', (chunk) => { + * assert.equal(typeof chunk, 'string'); + * console.log('Got %d characters of string data:', chunk.length); + * }); + * ``` + * @since v0.9.4 + * @param encoding The encoding to use. + */ + setEncoding(encoding: BufferEncoding): this; + /** + * The `readable.pause()` method will cause a stream in flowing mode to stop + * emitting `'data'` events, switching out of flowing mode. Any data that + * becomes available will remain in the internal buffer. + * + * ```js + * const readable = getReadableStreamSomehow(); + * readable.on('data', (chunk) => { + * console.log(`Received ${chunk.length} bytes of data.`); + * readable.pause(); + * console.log('There will be no additional data for 1 second.'); + * setTimeout(() => { + * console.log('Now data will start flowing again.'); + * readable.resume(); + * }, 1000); + * }); + * ``` + * + * The `readable.pause()` method has no effect if there is a `'readable'` event listener. + * @since v0.9.4 + */ + pause(): this; + /** + * The `readable.resume()` method causes an explicitly paused `Readable` stream to + * resume emitting `'data'` events, switching the stream into flowing mode. + * + * The `readable.resume()` method can be used to fully consume the data from a + * stream without actually processing any of that data: + * + * ```js + * getReadableStreamSomehow() + * .resume() + * .on('end', () => { + * console.log('Reached the end, but did not read anything.'); + * }); + * ``` + * + * The `readable.resume()` method has no effect if there is a `'readable'` event listener. + * @since v0.9.4 + */ + resume(): this; + /** + * The `readable.isPaused()` method returns the current operating state of the `Readable`. + * This is used primarily by the mechanism that underlies the `readable.pipe()` method. + * In most typical cases, there will be no reason to use this method directly. + * + * ```js + * const readable = new stream.Readable(); + * + * readable.isPaused(); // === false + * readable.pause(); + * readable.isPaused(); // === true + * readable.resume(); + * readable.isPaused(); // === false + * ``` + * @since v0.11.14 + */ + isPaused(): boolean; + /** + * The `readable.unpipe()` method detaches a `Writable` stream previously attached + * using the {@link pipe} method. + * + * If the `destination` is not specified, then _all_ pipes are detached. + * + * If the `destination` is specified, but no pipe is set up for it, then + * the method does nothing. + * + * ```js + * import fs from 'node:fs'; + * const readable = getReadableStreamSomehow(); + * const writable = fs.createWriteStream('file.txt'); + * // All the data from readable goes into 'file.txt', + * // but only for the first second. + * readable.pipe(writable); + * setTimeout(() => { + * console.log('Stop writing to file.txt.'); + * readable.unpipe(writable); + * console.log('Manually close the file stream.'); + * writable.end(); + * }, 1000); + * ``` + * @since v0.9.4 + * @param destination Optional specific stream to unpipe + */ + unpipe(destination?: NodeJS.WritableStream): this; + /** + * Passing `chunk` as `null` signals the end of the stream (EOF) and behaves the + * same as `readable.push(null)`, after which no more data can be written. The EOF + * signal is put at the end of the buffer and any buffered data will still be + * flushed. + * + * The `readable.unshift()` method pushes a chunk of data back into the internal + * buffer. This is useful in certain situations where a stream is being consumed by + * code that needs to "un-consume" some amount of data that it has optimistically + * pulled out of the source, so that the data can be passed on to some other party. + * + * The `stream.unshift(chunk)` method cannot be called after the `'end'` event + * has been emitted or a runtime error will be thrown. + * + * Developers using `stream.unshift()` often should consider switching to + * use of a `Transform` stream instead. See the `API for stream implementers` section for more information. + * + * ```js + * // Pull off a header delimited by \n\n. + * // Use unshift() if we get too much. + * // Call the callback with (error, header, stream). + * import { StringDecoder } from 'node:string_decoder'; + * function parseHeader(stream, callback) { + * stream.on('error', callback); + * stream.on('readable', onReadable); + * const decoder = new StringDecoder('utf8'); + * let header = ''; + * function onReadable() { + * let chunk; + * while (null !== (chunk = stream.read())) { + * const str = decoder.write(chunk); + * if (str.includes('\n\n')) { + * // Found the header boundary. + * const split = str.split(/\n\n/); + * header += split.shift(); + * const remaining = split.join('\n\n'); + * const buf = Buffer.from(remaining, 'utf8'); + * stream.removeListener('error', callback); + * // Remove the 'readable' listener before unshifting. + * stream.removeListener('readable', onReadable); + * if (buf.length) + * stream.unshift(buf); + * // Now the body of the message can be read from the stream. + * callback(null, header, stream); + * return; + * } + * // Still reading the header. + * header += str; + * } + * } + * } + * ``` + * + * Unlike {@link push}, `stream.unshift(chunk)` will not + * end the reading process by resetting the internal reading state of the stream. + * This can cause unexpected results if `readable.unshift()` is called during a + * read (i.e. from within a {@link _read} implementation on a + * custom stream). Following the call to `readable.unshift()` with an immediate {@link push} will reset the reading state appropriately, + * however it is best to simply avoid calling `readable.unshift()` while in the + * process of performing a read. + * @since v0.9.11 + * @param chunk Chunk of data to unshift onto the read queue. For streams not operating in object mode, `chunk` must + * be a {string}, {Buffer}, {TypedArray}, {DataView} or `null`. For object mode streams, `chunk` may be any JavaScript value. + * @param encoding Encoding of string chunks. Must be a valid `Buffer` encoding, such as `'utf8'` or `'ascii'`. + */ + unshift(chunk: any, encoding?: BufferEncoding): void; + /** + * Prior to Node.js 0.10, streams did not implement the entire `node:stream` module API as it is currently defined. (See `Compatibility` for more + * information.) + * + * When using an older Node.js library that emits `'data'` events and has a {@link pause} method that is advisory only, the `readable.wrap()` method can be used to create a `Readable` + * stream that uses + * the old stream as its data source. + * + * It will rarely be necessary to use `readable.wrap()` but the method has been + * provided as a convenience for interacting with older Node.js applications and + * libraries. + * + * ```js + * import { OldReader } from './old-api-module.js'; + * import { Readable } from 'node:stream'; + * const oreader = new OldReader(); + * const myReader = new Readable().wrap(oreader); + * + * myReader.on('readable', () => { + * myReader.read(); // etc. + * }); + * ``` + * @since v0.9.4 + * @param stream An "old style" readable stream + */ + wrap(stream: NodeJS.ReadableStream): this; + push(chunk: any, encoding?: BufferEncoding): boolean; + /** + * The iterator created by this method gives users the option to cancel the destruction + * of the stream if the `for await...of` loop is exited by `return`, `break`, or `throw`, + * or if the iterator should destroy the stream if the stream emitted an error during iteration. + * @since v16.3.0 + * @param options.destroyOnReturn When set to `false`, calling `return` on the async iterator, + * or exiting a `for await...of` iteration using a `break`, `return`, or `throw` will not destroy the stream. + * **Default: `true`**. + */ + iterator(options?: { destroyOnReturn?: boolean }): NodeJS.AsyncIterator; + /** + * This method allows mapping over the stream. The *fn* function will be called for every chunk in the stream. + * If the *fn* function returns a promise - that promise will be `await`ed before being passed to the result stream. + * @since v17.4.0, v16.14.0 + * @param fn a function to map over every chunk in the stream. Async or not. + * @returns a stream mapped with the function *fn*. + */ + map(fn: (data: any, options?: Pick) => any, options?: ArrayOptions): Readable; + /** + * This method allows filtering the stream. For each chunk in the stream the *fn* function will be called + * and if it returns a truthy value, the chunk will be passed to the result stream. + * If the *fn* function returns a promise - that promise will be `await`ed. + * @since v17.4.0, v16.14.0 + * @param fn a function to filter chunks from the stream. Async or not. + * @returns a stream filtered with the predicate *fn*. + */ + filter( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Readable; + /** + * This method allows iterating a stream. For each chunk in the stream the *fn* function will be called. + * If the *fn* function returns a promise - that promise will be `await`ed. + * + * This method is different from `for await...of` loops in that it can optionally process chunks concurrently. + * In addition, a `forEach` iteration can only be stopped by having passed a `signal` option + * and aborting the related AbortController while `for await...of` can be stopped with `break` or `return`. + * In either case the stream will be destroyed. + * + * This method is different from listening to the `'data'` event in that it uses the `readable` event + * in the underlying machinary and can limit the number of concurrent *fn* calls. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise for when the stream has finished. + */ + forEach( + fn: (data: any, options?: Pick) => void | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method allows easily obtaining the contents of a stream. + * + * As this method reads the entire stream into memory, it negates the benefits of streams. It's intended + * for interoperability and convenience, not as the primary way to consume streams. + * @since v17.5.0 + * @returns a promise containing an array with the contents of the stream. + */ + toArray(options?: Pick): Promise; + /** + * This method is similar to `Array.prototype.some` and calls *fn* on each chunk in the stream + * until the awaited return value is `true` (or any truthy value). Once an *fn* call on a chunk + * `await`ed return value is truthy, the stream is destroyed and the promise is fulfilled with `true`. + * If none of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `false`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to `true` if *fn* returned a truthy value for at least one of the chunks. + */ + some( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method is similar to `Array.prototype.find` and calls *fn* on each chunk in the stream + * to find a chunk with a truthy value for *fn*. Once an *fn* call's awaited return value is truthy, + * the stream is destroyed and the promise is fulfilled with value for which *fn* returned a truthy value. + * If all of the *fn* calls on the chunks return a falsy value, the promise is fulfilled with `undefined`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to the first chunk for which *fn* evaluated with a truthy value, + * or `undefined` if no element was found. + */ + find( + fn: (data: any, options?: Pick) => data is T, + options?: ArrayOptions, + ): Promise; + find( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method is similar to `Array.prototype.every` and calls *fn* on each chunk in the stream + * to check if all awaited return values are truthy value for *fn*. Once an *fn* call on a chunk + * `await`ed return value is falsy, the stream is destroyed and the promise is fulfilled with `false`. + * If all of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `true`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to `true` if *fn* returned a truthy value for every one of the chunks. + */ + every( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method returns a new stream by applying the given callback to each chunk of the stream + * and then flattening the result. + * + * It is possible to return a stream or another iterable or async iterable from *fn* and the result streams + * will be merged (flattened) into the returned stream. + * @since v17.5.0 + * @param fn a function to map over every chunk in the stream. May be async. May be a stream or generator. + * @returns a stream flat-mapped with the function *fn*. + */ + flatMap(fn: (data: any, options?: Pick) => any, options?: ArrayOptions): Readable; + /** + * This method returns a new stream with the first *limit* chunks dropped from the start. + * @since v17.5.0 + * @param limit the number of chunks to drop from the readable. + * @returns a stream with *limit* chunks dropped from the start. + */ + drop(limit: number, options?: Pick): Readable; + /** + * This method returns a new stream with the first *limit* chunks. + * @since v17.5.0 + * @param limit the number of chunks to take from the readable. + * @returns a stream with *limit* chunks taken. + */ + take(limit: number, options?: Pick): Readable; /** - * A utility method for creating a `Readable` from a web `ReadableStream`. - * @since v17.0.0 - * @experimental + * This method returns a new stream with chunks of the underlying stream paired with a counter + * in the form `[index, chunk]`. The first index value is `0` and it increases by 1 for each chunk produced. + * @since v17.5.0 + * @returns a stream of indexed pairs. */ - static fromWeb( - readableStream: streamWeb.ReadableStream, - options?: Pick, - ): Readable; + asIndexedPairs(options?: Pick): Readable; /** - * A utility method for creating a web `ReadableStream` from a `Readable`. - * @since v17.0.0 - * @experimental + * This method calls *fn* on each chunk of the stream in order, passing it the result from the calculation + * on the previous element. It returns a promise for the final value of the reduction. + * + * If no *initial* value is supplied the first chunk of the stream is used as the initial value. + * If the stream is empty, the promise is rejected with a `TypeError` with the `ERR_INVALID_ARGS` code property. + * + * The reducer function iterates the stream element-by-element which means that there is no *concurrency* parameter + * or parallelism. To perform a reduce concurrently, you can extract the async function to `readable.map` method. + * @since v17.5.0 + * @param fn a reducer function to call over every chunk in the stream. Async or not. + * @param initial the initial value to use in the reduction. + * @returns a promise for the final value of the reduction. + */ + reduce( + fn: (previous: any, data: any, options?: Pick) => T, + initial?: undefined, + options?: Pick, + ): Promise; + reduce( + fn: (previous: T, data: any, options?: Pick) => T, + initial: T, + options?: Pick, + ): Promise; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; + /** + * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the readable + * stream will release any internal resources and subsequent calls to `push()` will be ignored. + * + * Once `destroy()` has been called any further calls will be a no-op and no + * further errors except from `_destroy()` may be emitted as `'error'`. + * + * Implementors should not override this method, but instead implement `readable._destroy()`. + * @since v8.0.0 + * @param error Error which will be passed as payload in `'error'` event + */ + destroy(error?: Error): this; + /** + * Event emitter + * The defined events on documents including: + * 1. close + * 2. data + * 3. end + * 4. error + * 5. pause + * 6. readable + * 7. resume + */ + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: any) => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "data", chunk: any): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "pause"): boolean; + emit(event: "readable"): boolean; + emit(event: "resume"): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: any) => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "readable", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: any) => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "readable", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: any) => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: any) => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "data", listener: (chunk: any) => void): this; + removeListener(event: "end", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "pause", listener: () => void): this; + removeListener(event: "readable", listener: () => void): this; + removeListener(event: "resume", listener: () => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; + [Symbol.asyncIterator](): NodeJS.AsyncIterator; + /** + * Calls `readable.destroy()` with an `AbortError` and returns a promise that fulfills when the stream is finished. + * @since v20.4.0 */ - static toWeb(streamReadable: Readable): streamWeb.ReadableStream; + [Symbol.asyncDispose](): Promise; } - interface WritableOptions extends StreamOptions { + interface WritableOptions extends StreamOptions { decodeStrings?: boolean | undefined; defaultEncoding?: BufferEncoding | undefined; write?( - this: Writable, + this: T, chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void, ): void; writev?( - this: Writable, + this: T, chunks: Array<{ chunk: any; encoding: BufferEncoding; }>, callback: (error?: Error | null) => void, ): void; - final?(this: Writable, callback: (error?: Error | null) => void): void; + final?(this: T, callback: (error?: Error | null) => void): void; } /** * @since v0.9.4 */ - class Writable extends WritableBase { + class Writable extends Stream implements NodeJS.WritableStream { /** * A utility method for creating a `Writable` from a web `WritableStream`. * @since v17.0.0 - * @experimental */ static fromWeb( writableStream: streamWeb.WritableStream, @@ -1018,30 +723,307 @@ declare module "stream" { /** * A utility method for creating a web `WritableStream` from a `Writable`. * @since v17.0.0 - * @experimental */ static toWeb(streamWritable: Writable): streamWeb.WritableStream; + /** + * Is `true` if it is safe to call `writable.write()`, which means + * the stream has not been destroyed, errored, or ended. + * @since v11.4.0 + */ + readonly writable: boolean; + /** + * Returns whether the stream was destroyed or errored before emitting `'finish'`. + * @since v18.0.0, v16.17.0 + */ + readonly writableAborted: boolean; + /** + * Is `true` after `writable.end()` has been called. This property + * does not indicate whether the data has been flushed, for this use `writable.writableFinished` instead. + * @since v12.9.0 + */ + readonly writableEnded: boolean; + /** + * Is set to `true` immediately before the `'finish'` event is emitted. + * @since v12.6.0 + */ + readonly writableFinished: boolean; + /** + * Return the value of `highWaterMark` passed when creating this `Writable`. + * @since v9.3.0 + */ + readonly writableHighWaterMark: number; + /** + * This property contains the number of bytes (or objects) in the queue + * ready to be written. The value provides introspection data regarding + * the status of the `highWaterMark`. + * @since v9.4.0 + */ + readonly writableLength: number; + /** + * Getter for the property `objectMode` of a given `Writable` stream. + * @since v12.3.0 + */ + readonly writableObjectMode: boolean; + /** + * Number of times `writable.uncork()` needs to be + * called in order to fully uncork the stream. + * @since v13.2.0, v12.16.0 + */ + readonly writableCorked: number; + /** + * Is `true` after `writable.destroy()` has been called. + * @since v8.0.0 + */ + destroyed: boolean; + /** + * Is `true` after `'close'` has been emitted. + * @since v18.0.0 + */ + readonly closed: boolean; + /** + * Returns error if the stream has been destroyed with an error. + * @since v18.0.0 + */ + readonly errored: Error | null; + /** + * Is `true` if the stream's buffer has been full and stream will emit `'drain'`. + * @since v15.2.0, v14.17.0 + */ + readonly writableNeedDrain: boolean; + constructor(opts?: WritableOptions); + _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; + _writev?( + chunks: Array<{ + chunk: any; + encoding: BufferEncoding; + }>, + callback: (error?: Error | null) => void, + ): void; + _construct?(callback: (error?: Error | null) => void): void; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; + _final(callback: (error?: Error | null) => void): void; + /** + * The `writable.write()` method writes some data to the stream, and calls the + * supplied `callback` once the data has been fully handled. If an error + * occurs, the `callback` will be called with the error as its + * first argument. The `callback` is called asynchronously and before `'error'` is + * emitted. + * + * The return value is `true` if the internal buffer is less than the `highWaterMark` configured when the stream was created after admitting `chunk`. + * If `false` is returned, further attempts to write data to the stream should + * stop until the `'drain'` event is emitted. + * + * While a stream is not draining, calls to `write()` will buffer `chunk`, and + * return false. Once all currently buffered chunks are drained (accepted for + * delivery by the operating system), the `'drain'` event will be emitted. + * Once `write()` returns false, do not write more chunks + * until the `'drain'` event is emitted. While calling `write()` on a stream that + * is not draining is allowed, Node.js will buffer all written chunks until + * maximum memory usage occurs, at which point it will abort unconditionally. + * Even before it aborts, high memory usage will cause poor garbage collector + * performance and high RSS (which is not typically released back to the system, + * even after the memory is no longer required). Since TCP sockets may never + * drain if the remote peer does not read the data, writing a socket that is + * not draining may lead to a remotely exploitable vulnerability. + * + * Writing data while the stream is not draining is particularly + * problematic for a `Transform`, because the `Transform` streams are paused + * by default until they are piped or a `'data'` or `'readable'` event handler + * is added. + * + * If the data to be written can be generated or fetched on demand, it is + * recommended to encapsulate the logic into a `Readable` and use {@link pipe}. However, if calling `write()` is preferred, it is + * possible to respect backpressure and avoid memory issues using the `'drain'` event: + * + * ```js + * function write(data, cb) { + * if (!stream.write(data)) { + * stream.once('drain', cb); + * } else { + * process.nextTick(cb); + * } + * } + * + * // Wait for cb to be called before doing any other write. + * write('hello', () => { + * console.log('Write completed, do more writes now.'); + * }); + * ``` + * + * A `Writable` stream in object mode will always ignore the `encoding` argument. + * @since v0.9.4 + * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer}, + * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`. + * @param [encoding='utf8'] The encoding, if `chunk` is a string. + * @param callback Callback for when this chunk of data is flushed. + * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean; + write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean; + /** + * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream. + * @since v0.11.15 + * @param encoding The new default encoding + */ + setDefaultEncoding(encoding: BufferEncoding): this; + /** + * Calling the `writable.end()` method signals that no more data will be written + * to the `Writable`. The optional `chunk` and `encoding` arguments allow one + * final additional chunk of data to be written immediately before closing the + * stream. + * + * Calling the {@link write} method after calling {@link end} will raise an error. + * + * ```js + * // Write 'hello, ' and then end with 'world!'. + * import fs from 'node:fs'; + * const file = fs.createWriteStream('example.txt'); + * file.write('hello, '); + * file.end('world!'); + * // Writing more now is not allowed! + * ``` + * @since v0.9.4 + * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer}, + * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`. + * @param encoding The encoding if `chunk` is a string + * @param callback Callback for when the stream is finished. + */ + end(cb?: () => void): this; + end(chunk: any, cb?: () => void): this; + end(chunk: any, encoding: BufferEncoding, cb?: () => void): this; + /** + * The `writable.cork()` method forces all written data to be buffered in memory. + * The buffered data will be flushed when either the {@link uncork} or {@link end} methods are called. + * + * The primary intent of `writable.cork()` is to accommodate a situation in which + * several small chunks are written to the stream in rapid succession. Instead of + * immediately forwarding them to the underlying destination, `writable.cork()` buffers all the chunks until `writable.uncork()` is called, which will pass them + * all to `writable._writev()`, if present. This prevents a head-of-line blocking + * situation where data is being buffered while waiting for the first small chunk + * to be processed. However, use of `writable.cork()` without implementing `writable._writev()` may have an adverse effect on throughput. + * + * See also: `writable.uncork()`, `writable._writev()`. + * @since v0.11.2 + */ + cork(): void; + /** + * The `writable.uncork()` method flushes all data buffered since {@link cork} was called. + * + * When using `writable.cork()` and `writable.uncork()` to manage the buffering + * of writes to a stream, defer calls to `writable.uncork()` using `process.nextTick()`. Doing so allows batching of all `writable.write()` calls that occur within a given Node.js event + * loop phase. + * + * ```js + * stream.cork(); + * stream.write('some '); + * stream.write('data '); + * process.nextTick(() => stream.uncork()); + * ``` + * + * If the `writable.cork()` method is called multiple times on a stream, the + * same number of calls to `writable.uncork()` must be called to flush the buffered + * data. + * + * ```js + * stream.cork(); + * stream.write('some '); + * stream.cork(); + * stream.write('data '); + * process.nextTick(() => { + * stream.uncork(); + * // The data will not be flushed until uncork() is called a second time. + * stream.uncork(); + * }); + * ``` + * + * See also: `writable.cork()`. + * @since v0.11.2 + */ + uncork(): void; + /** + * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the writable + * stream has ended and subsequent calls to `write()` or `end()` will result in + * an `ERR_STREAM_DESTROYED` error. + * This is a destructive and immediate way to destroy a stream. Previous calls to `write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error. + * Use `end()` instead of destroy if data should flush before close, or wait for + * the `'drain'` event before destroying the stream. + * + * Once `destroy()` has been called any further calls will be a no-op and no + * further errors except from `_destroy()` may be emitted as `'error'`. + * + * Implementors should not override this method, + * but instead implement `writable._destroy()`. + * @since v8.0.0 + * @param error Optional, an error to emit with `'error'` event. + */ + destroy(error?: Error): this; + /** + * Event emitter + * The defined events on documents including: + * 1. close + * 2. drain + * 3. error + * 4. finish + * 5. pipe + * 6. unpipe + */ + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pipe", listener: (src: Readable) => void): this; + addListener(event: "unpipe", listener: (src: Readable) => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "drain"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "pipe", src: Readable): boolean; + emit(event: "unpipe", src: Readable): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pipe", listener: (src: Readable) => void): this; + on(event: "unpipe", listener: (src: Readable) => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pipe", listener: (src: Readable) => void): this; + once(event: "unpipe", listener: (src: Readable) => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pipe", listener: (src: Readable) => void): this; + prependListener(event: "unpipe", listener: (src: Readable) => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "drain", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "finish", listener: () => void): this; + removeListener(event: "pipe", listener: (src: Readable) => void): this; + removeListener(event: "unpipe", listener: (src: Readable) => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; } - interface DuplexOptions extends ReadableOptions, WritableOptions { + interface DuplexOptions extends ReadableOptions, WritableOptions { allowHalfOpen?: boolean | undefined; readableObjectMode?: boolean | undefined; writableObjectMode?: boolean | undefined; readableHighWaterMark?: number | undefined; writableHighWaterMark?: number | undefined; writableCorked?: number | undefined; - construct?(this: Duplex, callback: (error?: Error | null) => void): void; - read?(this: Duplex, size: number): void; - write?(this: Duplex, chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; - writev?( - this: Duplex, - chunks: Array<{ - chunk: any; - encoding: BufferEncoding; - }>, - callback: (error?: Error | null) => void, - ): void; - final?(this: Duplex, callback: (error?: Error | null) => void): void; - destroy?(this: Duplex, error: Error | null, callback: (error?: Error | null) => void): void; } /** * Duplex streams are streams that implement both the `Readable` and `Writable` interfaces. @@ -1053,17 +1035,7 @@ declare module "stream" { * * `crypto streams` * @since v0.9.4 */ - class Duplex extends ReadableBase implements WritableBase { - readonly writable: boolean; - readonly writableEnded: boolean; - readonly writableFinished: boolean; - readonly writableHighWaterMark: number; - readonly writableLength: number; - readonly writableObjectMode: boolean; - readonly writableCorked: number; - readonly writableNeedDrain: boolean; - readonly closed: boolean; - readonly errored: Error | null; + class Duplex extends Stream implements NodeJS.ReadWriteStream { /** * If `false` then the stream will automatically end the writable side when the * readable side ends. Set initially by the `allowHalfOpen` constructor option, @@ -1108,28 +1080,9 @@ declare module "stream" { | Promise | Object, ): Duplex; - _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; - _writev?( - chunks: Array<{ - chunk: any; - encoding: BufferEncoding; - }>, - callback: (error?: Error | null) => void, - ): void; - _destroy(error: Error | null, callback: (error?: Error | null) => void): void; - _final(callback: (error?: Error | null) => void): void; - write(chunk: any, encoding?: BufferEncoding, cb?: (error: Error | null | undefined) => void): boolean; - write(chunk: any, cb?: (error: Error | null | undefined) => void): boolean; - setDefaultEncoding(encoding: BufferEncoding): this; - end(cb?: () => void): this; - end(chunk: any, cb?: () => void): this; - end(chunk: any, encoding?: BufferEncoding, cb?: () => void): this; - cork(): void; - uncork(): void; /** * A utility method for creating a web `ReadableStream` and `WritableStream` from a `Duplex`. * @since v17.0.0 - * @experimental */ static toWeb(streamDuplex: Duplex): { readable: streamWeb.ReadableStream; @@ -1138,7 +1091,6 @@ declare module "stream" { /** * A utility method for creating a `Duplex` from a web `ReadableStream` and `WritableStream`. * @since v17.0.0 - * @experimental */ static fromWeb( duplexStream: { @@ -1250,6 +1202,7 @@ declare module "stream" { removeListener(event: "unpipe", listener: (src: Readable) => void): this; removeListener(event: string | symbol, listener: (...args: any[]) => void): this; } + interface Duplex extends Readable, Writable {} /** * The utility function `duplexPair` returns an Array with two items, * each being a `Duplex` stream connected to the other side: @@ -1270,27 +1223,9 @@ declare module "stream" { */ function duplexPair(options?: DuplexOptions): [Duplex, Duplex]; type TransformCallback = (error?: Error | null, data?: any) => void; - interface TransformOptions extends DuplexOptions { - construct?(this: Transform, callback: (error?: Error | null) => void): void; - read?(this: Transform, size: number): void; - write?( - this: Transform, - chunk: any, - encoding: BufferEncoding, - callback: (error?: Error | null) => void, - ): void; - writev?( - this: Transform, - chunks: Array<{ - chunk: any; - encoding: BufferEncoding; - }>, - callback: (error?: Error | null) => void, - ): void; - final?(this: Transform, callback: (error?: Error | null) => void): void; - destroy?(this: Transform, error: Error | null, callback: (error?: Error | null) => void): void; - transform?(this: Transform, chunk: any, encoding: BufferEncoding, callback: TransformCallback): void; - flush?(this: Transform, callback: TransformCallback): void; + interface TransformOptions extends DuplexOptions { + transform?(this: T, chunk: any, encoding: BufferEncoding, callback: TransformCallback): void; + flush?(this: T, callback: TransformCallback): void; } /** * Transform streams are `Duplex` streams where the output is in some way @@ -1706,19 +1641,15 @@ declare module "stream" { /** * Returns whether the stream has encountered an error. * @since v17.3.0, v16.14.0 - * @experimental */ function isErrored(stream: Readable | Writable | NodeJS.ReadableStream | NodeJS.WritableStream): boolean; /** * Returns whether the stream is readable. * @since v17.4.0, v16.14.0 - * @experimental */ function isReadable(stream: Readable | NodeJS.ReadableStream): boolean; - const promises: typeof streamPromises; - const consumers: typeof streamConsumers; } - export = internal; + export = Stream; } declare module "node:stream" { import stream = require("stream"); diff --git a/node_modules/@types/node/stream/consumers.d.ts b/node_modules/@types/node/stream/consumers.d.ts index 5ad9cbab9..746d6e508 100644 --- a/node_modules/@types/node/stream/consumers.d.ts +++ b/node_modules/@types/node/stream/consumers.d.ts @@ -1,11 +1,37 @@ +/** + * The utility consumer functions provide common options for consuming + * streams. + * @since v16.7.0 + */ declare module "stream/consumers" { import { Blob as NodeBlob } from "node:buffer"; - import { Readable } from "node:stream"; - function buffer(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; - function text(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; - function arrayBuffer(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; - function blob(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; - function json(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + import { ReadableStream as WebReadableStream } from "node:stream/web"; + /** + * @since v16.7.0 + * @returns Fulfills with an `ArrayBuffer` containing the full contents of the stream. + */ + function arrayBuffer(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; + /** + * @since v16.7.0 + * @returns Fulfills with a `Blob` containing the full contents of the stream. + */ + function blob(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; + /** + * @since v16.7.0 + * @returns Fulfills with a `Buffer` containing the full contents of the stream. + */ + function buffer(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; + /** + * @since v16.7.0 + * @returns Fulfills with the contents of the stream parsed as a + * UTF-8 encoded string that is then passed through `JSON.parse()`. + */ + function json(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; + /** + * @since v16.7.0 + * @returns Fulfills with the contents of the stream parsed as a UTF-8 encoded string. + */ + function text(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable): Promise; } declare module "node:stream/consumers" { export * from "stream/consumers"; diff --git a/node_modules/@types/node/stream/web.d.ts b/node_modules/@types/node/stream/web.d.ts index 5da8a984f..881e29c08 100644 --- a/node_modules/@types/node/stream/web.d.ts +++ b/node_modules/@types/node/stream/web.d.ts @@ -6,6 +6,8 @@ type _CountQueuingStrategy = typeof globalThis extends { onmessage: any } ? {} : import("stream/web").CountQueuingStrategy; type _DecompressionStream = typeof globalThis extends { onmessage: any; ReportingObserver: any } ? {} : import("stream/web").DecompressionStream; +type _QueuingStrategy = typeof globalThis extends { onmessage: any } ? {} + : import("stream/web").QueuingStrategy; type _ReadableByteStreamController = typeof globalThis extends { onmessage: any } ? {} : import("stream/web").ReadableByteStreamController; type _ReadableStream = typeof globalThis extends { onmessage: any } ? {} @@ -97,7 +99,7 @@ declare module "stream/web" { signal?: AbortSignal; } interface ReadableStreamGenericReader { - readonly closed: Promise; + readonly closed: Promise; cancel(reason?: any): Promise; } type ReadableStreamController = ReadableStreamDefaultController; @@ -143,6 +145,9 @@ declare module "stream/web" { interface TransformerTransformCallback { (chunk: I, controller: TransformStreamDefaultController): void | PromiseLike; } + interface TransformerCancelCallback { + (reason: any): void | PromiseLike; + } interface UnderlyingByteSource { autoAllocateChunkSize?: number; cancel?: ReadableStreamErrorCallback; @@ -205,7 +210,12 @@ declare module "stream/web" { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader) */ interface ReadableStreamBYOBReader extends ReadableStreamGenericReader { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/read) */ - read(view: T): Promise>; + read( + view: T, + options?: { + min?: number; + }, + ): Promise>; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/releaseLock) */ releaseLock(): void; } @@ -256,6 +266,7 @@ declare module "stream/web" { readableType?: undefined; start?: TransformerStartCallback; transform?: TransformerTransformCallback; + cancel?: TransformerCancelCallback; writableType?: undefined; } interface TransformStream { @@ -302,9 +313,9 @@ declare module "stream/web" { * sink. */ interface WritableStreamDefaultWriter { - readonly closed: Promise; + readonly closed: Promise; readonly desiredSize: number | null; - readonly ready: Promise; + readonly ready: Promise; abort(reason?: any): Promise; close(): Promise; releaseLock(): void; @@ -478,6 +489,8 @@ declare module "stream/web" { } : typeof import("stream/web").DecompressionStream; + interface QueuingStrategy extends _QueuingStrategy {} + interface ReadableByteStreamController extends _ReadableByteStreamController {} /** * `ReadableByteStreamController` class is a global reference for `import { ReadableByteStreamController } from 'node:stream/web'`. diff --git a/node_modules/@types/node/test.d.ts b/node_modules/@types/node/test.d.ts index 42ff08e12..5bd292699 100644 --- a/node_modules/@types/node/test.d.ts +++ b/node_modules/@types/node/test.d.ts @@ -80,26 +80,8 @@ */ declare module "node:test" { import { Readable } from "node:stream"; - /** - * **Note:** `shard` is used to horizontally parallelize test running across - * machines or processes, ideal for large-scale executions across varied - * environments. It's incompatible with `watch` mode, tailored for rapid - * code iteration by automatically rerunning tests on file changes. - * - * ```js - * import { tap } from 'node:test/reporters'; - * import { run } from 'node:test'; - * import process from 'node:process'; - * import path from 'node:path'; - * - * run({ files: [path.resolve('./tests/test.js')] }) - * .compose(tap) - * .pipe(process.stdout); - * ``` - * @since v18.9.0, v16.19.0 - * @param options Configuration options for running tests. - */ - function run(options?: RunOptions): TestsStream; + import TestFn = test.TestFn; + import TestOptions = test.TestOptions; /** * The `test()` function is the value imported from the `test` module. Each * invocation of this function results in reporting the test to the `TestsStream`. @@ -144,1877 +126,1980 @@ declare module "node:test" { function test(options?: TestOptions, fn?: TestFn): Promise; function test(fn?: TestFn): Promise; namespace test { - export { - after, - afterEach, - before, - beforeEach, - describe, - it, - mock, - only, - run, - skip, - snapshot, - suite, - test, - todo, - }; + export { test }; + export { suite as describe, test as it }; } - /** - * The `suite()` function is imported from the `node:test` module. - * @param name The name of the suite, which is displayed when reporting test results. - * Defaults to the `name` property of `fn`, or `''` if `fn` does not have a name. - * @param options Configuration options for the suite. This supports the same options as {@link test}. - * @param fn The suite function declaring nested tests and suites. The first argument to this function is a {@link SuiteContext} object. - * @return Immediately fulfilled with `undefined`. - * @since v20.13.0 - */ - function suite(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; - function suite(name?: string, fn?: SuiteFn): Promise; - function suite(options?: TestOptions, fn?: SuiteFn): Promise; - function suite(fn?: SuiteFn): Promise; - namespace suite { - /** - * Shorthand for skipping a suite. This is the same as calling {@link suite} with `options.skip` set to `true`. - * @since v20.13.0 - */ - function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; - function skip(name?: string, fn?: SuiteFn): Promise; - function skip(options?: TestOptions, fn?: SuiteFn): Promise; - function skip(fn?: SuiteFn): Promise; + namespace test { /** - * Shorthand for marking a suite as `TODO`. This is the same as calling {@link suite} with `options.todo` set to `true`. - * @since v20.13.0 + * **Note:** `shard` is used to horizontally parallelize test running across + * machines or processes, ideal for large-scale executions across varied + * environments. It's incompatible with `watch` mode, tailored for rapid + * code iteration by automatically rerunning tests on file changes. + * + * ```js + * import { tap } from 'node:test/reporters'; + * import { run } from 'node:test'; + * import process from 'node:process'; + * import path from 'node:path'; + * + * run({ files: [path.resolve('./tests/test.js')] }) + * .compose(tap) + * .pipe(process.stdout); + * ``` + * @since v18.9.0, v16.19.0 + * @param options Configuration options for running tests. */ - function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; - function todo(name?: string, fn?: SuiteFn): Promise; - function todo(options?: TestOptions, fn?: SuiteFn): Promise; - function todo(fn?: SuiteFn): Promise; + function run(options?: RunOptions): TestsStream; /** - * Shorthand for marking a suite as `only`. This is the same as calling {@link suite} with `options.only` set to `true`. + * The `suite()` function is imported from the `node:test` module. + * @param name The name of the suite, which is displayed when reporting test results. + * Defaults to the `name` property of `fn`, or `''` if `fn` does not have a name. + * @param options Configuration options for the suite. This supports the same options as {@link test}. + * @param fn The suite function declaring nested tests and suites. The first argument to this function is a {@link SuiteContext} object. + * @return Immediately fulfilled with `undefined`. * @since v20.13.0 */ - function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; - function only(name?: string, fn?: SuiteFn): Promise; - function only(options?: TestOptions, fn?: SuiteFn): Promise; - function only(fn?: SuiteFn): Promise; - } - /** - * Alias for {@link suite}. - * - * The `describe()` function is imported from the `node:test` module. - */ - function describe(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; - function describe(name?: string, fn?: SuiteFn): Promise; - function describe(options?: TestOptions, fn?: SuiteFn): Promise; - function describe(fn?: SuiteFn): Promise; - namespace describe { - /** - * Shorthand for skipping a suite. This is the same as calling {@link describe} with `options.skip` set to `true`. - * @since v18.15.0 - */ - function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; - function skip(name?: string, fn?: SuiteFn): Promise; - function skip(options?: TestOptions, fn?: SuiteFn): Promise; - function skip(fn?: SuiteFn): Promise; - /** - * Shorthand for marking a suite as `TODO`. This is the same as calling {@link describe} with `options.todo` set to `true`. - * @since v18.15.0 - */ - function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; - function todo(name?: string, fn?: SuiteFn): Promise; - function todo(options?: TestOptions, fn?: SuiteFn): Promise; - function todo(fn?: SuiteFn): Promise; - /** - * Shorthand for marking a suite as `only`. This is the same as calling {@link describe} with `options.only` set to `true`. - * @since v18.15.0 - */ - function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; - function only(name?: string, fn?: SuiteFn): Promise; - function only(options?: TestOptions, fn?: SuiteFn): Promise; - function only(fn?: SuiteFn): Promise; - } - /** - * Alias for {@link test}. - * - * The `it()` function is imported from the `node:test` module. - * @since v18.6.0, v16.17.0 - */ - function it(name?: string, options?: TestOptions, fn?: TestFn): Promise; - function it(name?: string, fn?: TestFn): Promise; - function it(options?: TestOptions, fn?: TestFn): Promise; - function it(fn?: TestFn): Promise; - namespace it { + function suite(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function suite(name?: string, fn?: SuiteFn): Promise; + function suite(options?: TestOptions, fn?: SuiteFn): Promise; + function suite(fn?: SuiteFn): Promise; + namespace suite { + /** + * Shorthand for skipping a suite. This is the same as calling {@link suite} with `options.skip` set to `true`. + * @since v20.13.0 + */ + function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function skip(name?: string, fn?: SuiteFn): Promise; + function skip(options?: TestOptions, fn?: SuiteFn): Promise; + function skip(fn?: SuiteFn): Promise; + /** + * Shorthand for marking a suite as `TODO`. This is the same as calling {@link suite} with `options.todo` set to `true`. + * @since v20.13.0 + */ + function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function todo(name?: string, fn?: SuiteFn): Promise; + function todo(options?: TestOptions, fn?: SuiteFn): Promise; + function todo(fn?: SuiteFn): Promise; + /** + * Shorthand for marking a suite as `only`. This is the same as calling {@link suite} with `options.only` set to `true`. + * @since v20.13.0 + */ + function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function only(name?: string, fn?: SuiteFn): Promise; + function only(options?: TestOptions, fn?: SuiteFn): Promise; + function only(fn?: SuiteFn): Promise; + } /** - * Shorthand for skipping a test. This is the same as calling {@link it} with `options.skip` set to `true`. + * Shorthand for skipping a test. This is the same as calling {@link test} with `options.skip` set to `true`. + * @since v20.2.0 */ function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise; function skip(name?: string, fn?: TestFn): Promise; function skip(options?: TestOptions, fn?: TestFn): Promise; function skip(fn?: TestFn): Promise; /** - * Shorthand for marking a test as `TODO`. This is the same as calling {@link it} with `options.todo` set to `true`. + * Shorthand for marking a test as `TODO`. This is the same as calling {@link test} with `options.todo` set to `true`. + * @since v20.2.0 */ function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise; function todo(name?: string, fn?: TestFn): Promise; function todo(options?: TestOptions, fn?: TestFn): Promise; function todo(fn?: TestFn): Promise; /** - * Shorthand for marking a test as `only`. This is the same as calling {@link it} with `options.only` set to `true`. - * @since v18.15.0 + * Shorthand for marking a test as `only`. This is the same as calling {@link test} with `options.only` set to `true`. + * @since v20.2.0 */ function only(name?: string, options?: TestOptions, fn?: TestFn): Promise; function only(name?: string, fn?: TestFn): Promise; function only(options?: TestOptions, fn?: TestFn): Promise; function only(fn?: TestFn): Promise; - } - /** - * Shorthand for skipping a test. This is the same as calling {@link test} with `options.skip` set to `true`. - * @since v20.2.0 - */ - function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise; - function skip(name?: string, fn?: TestFn): Promise; - function skip(options?: TestOptions, fn?: TestFn): Promise; - function skip(fn?: TestFn): Promise; - /** - * Shorthand for marking a test as `TODO`. This is the same as calling {@link test} with `options.todo` set to `true`. - * @since v20.2.0 - */ - function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise; - function todo(name?: string, fn?: TestFn): Promise; - function todo(options?: TestOptions, fn?: TestFn): Promise; - function todo(fn?: TestFn): Promise; - /** - * Shorthand for marking a test as `only`. This is the same as calling {@link test} with `options.only` set to `true`. - * @since v20.2.0 - */ - function only(name?: string, options?: TestOptions, fn?: TestFn): Promise; - function only(name?: string, fn?: TestFn): Promise; - function only(options?: TestOptions, fn?: TestFn): Promise; - function only(fn?: TestFn): Promise; - /** - * The type of a function passed to {@link test}. The first argument to this function is a {@link TestContext} object. - * If the test uses callbacks, the callback function is passed as the second argument. - */ - type TestFn = (t: TestContext, done: (result?: any) => void) => void | Promise; - /** - * The type of a suite test function. The argument to this function is a {@link SuiteContext} object. - */ - type SuiteFn = (s: SuiteContext) => void | Promise; - interface TestShard { - /** - * A positive integer between 1 and `total` that specifies the index of the shard to run. - */ - index: number; - /** - * A positive integer that specifies the total number of shards to split the test files to. - */ - total: number; - } - interface RunOptions { - /** - * If a number is provided, then that many test processes would run in parallel, where each process corresponds to one test file. - * If `true`, it would run `os.availableParallelism() - 1` test files in parallel. If `false`, it would only run one test file at a time. - * @default false - */ - concurrency?: number | boolean | undefined; - /** - * An array containing the list of files to run. If omitted, files are run according to the - * [test runner execution model](https://nodejs.org/docs/latest-v22.x/api/test.html#test-runner-execution-model). - */ - files?: readonly string[] | undefined; - /** - * Configures the test runner to exit the process once all known - * tests have finished executing even if the event loop would - * otherwise remain active. - * @default false - */ - forceExit?: boolean | undefined; - /** - * An array containing the list of glob patterns to match test files. - * This option cannot be used together with `files`. If omitted, files are run according to the - * [test runner execution model](https://nodejs.org/docs/latest-v22.x/api/test.html#test-runner-execution-model). - * @since v22.6.0 - */ - globPatterns?: readonly string[] | undefined; /** - * Sets inspector port of test child process. - * If a nullish value is provided, each process gets its own port, - * incremented from the primary's `process.debugPort`. - * @default undefined - */ - inspectPort?: number | (() => number) | undefined; - /** - * If truthy, the test context will only run tests that have the `only` option set - */ - only?: boolean | undefined; - /** - * A function that accepts the `TestsStream` instance and can be used to setup listeners before any tests are run. - * @default undefined - */ - setup?: ((reporter: TestsStream) => void | Promise) | undefined; - /** - * Allows aborting an in-progress test execution. - */ - signal?: AbortSignal | undefined; - /** - * If provided, only run tests whose name matches the provided pattern. - * Strings are interpreted as JavaScript regular expressions. - * @default undefined - */ - testNamePatterns?: string | RegExp | ReadonlyArray | undefined; - /** - * A String, RegExp or a RegExp Array, that can be used to exclude running tests whose - * name matches the provided pattern. Test name patterns are interpreted as JavaScript - * regular expressions. For each test that is executed, any corresponding test hooks, - * such as `beforeEach()`, are also run. - * @default undefined - * @since v22.1.0 - */ - testSkipPatterns?: string | RegExp | ReadonlyArray | undefined; - /** - * The number of milliseconds after which the test execution will fail. - * If unspecified, subtests inherit this value from their parent. - * @default Infinity - */ - timeout?: number | undefined; - /** - * Whether to run in watch mode or not. - * @default false - */ - watch?: boolean | undefined; - /** - * Running tests in a specific shard. - * @default undefined - */ - shard?: TestShard | undefined; - } - /** - * A successful call to `run()` will return a new `TestsStream` object, streaming a series of events representing the execution of the tests. - * - * Some of the events are guaranteed to be emitted in the same order as the tests are defined, while others are emitted in the order that the tests execute. - * @since v18.9.0, v16.19.0 - */ - class TestsStream extends Readable implements NodeJS.ReadableStream { - addListener(event: "test:coverage", listener: (data: TestCoverage) => void): this; - addListener(event: "test:complete", listener: (data: TestComplete) => void): this; - addListener(event: "test:dequeue", listener: (data: TestDequeue) => void): this; - addListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; - addListener(event: "test:enqueue", listener: (data: TestEnqueue) => void): this; - addListener(event: "test:fail", listener: (data: TestFail) => void): this; - addListener(event: "test:pass", listener: (data: TestPass) => void): this; - addListener(event: "test:plan", listener: (data: TestPlan) => void): this; - addListener(event: "test:start", listener: (data: TestStart) => void): this; - addListener(event: "test:stderr", listener: (data: TestStderr) => void): this; - addListener(event: "test:stdout", listener: (data: TestStdout) => void): this; - addListener(event: "test:watch:drained", listener: () => void): this; - addListener(event: string, listener: (...args: any[]) => void): this; - emit(event: "test:coverage", data: TestCoverage): boolean; - emit(event: "test:complete", data: TestComplete): boolean; - emit(event: "test:dequeue", data: TestDequeue): boolean; - emit(event: "test:diagnostic", data: DiagnosticData): boolean; - emit(event: "test:enqueue", data: TestEnqueue): boolean; - emit(event: "test:fail", data: TestFail): boolean; - emit(event: "test:pass", data: TestPass): boolean; - emit(event: "test:plan", data: TestPlan): boolean; - emit(event: "test:start", data: TestStart): boolean; - emit(event: "test:stderr", data: TestStderr): boolean; - emit(event: "test:stdout", data: TestStdout): boolean; - emit(event: "test:watch:drained"): boolean; - emit(event: string | symbol, ...args: any[]): boolean; - on(event: "test:coverage", listener: (data: TestCoverage) => void): this; - on(event: "test:complete", listener: (data: TestComplete) => void): this; - on(event: "test:dequeue", listener: (data: TestDequeue) => void): this; - on(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; - on(event: "test:enqueue", listener: (data: TestEnqueue) => void): this; - on(event: "test:fail", listener: (data: TestFail) => void): this; - on(event: "test:pass", listener: (data: TestPass) => void): this; - on(event: "test:plan", listener: (data: TestPlan) => void): this; - on(event: "test:start", listener: (data: TestStart) => void): this; - on(event: "test:stderr", listener: (data: TestStderr) => void): this; - on(event: "test:stdout", listener: (data: TestStdout) => void): this; - on(event: "test:watch:drained", listener: () => void): this; - on(event: string, listener: (...args: any[]) => void): this; - once(event: "test:coverage", listener: (data: TestCoverage) => void): this; - once(event: "test:complete", listener: (data: TestComplete) => void): this; - once(event: "test:dequeue", listener: (data: TestDequeue) => void): this; - once(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; - once(event: "test:enqueue", listener: (data: TestEnqueue) => void): this; - once(event: "test:fail", listener: (data: TestFail) => void): this; - once(event: "test:pass", listener: (data: TestPass) => void): this; - once(event: "test:plan", listener: (data: TestPlan) => void): this; - once(event: "test:start", listener: (data: TestStart) => void): this; - once(event: "test:stderr", listener: (data: TestStderr) => void): this; - once(event: "test:stdout", listener: (data: TestStdout) => void): this; - once(event: "test:watch:drained", listener: () => void): this; - once(event: string, listener: (...args: any[]) => void): this; - prependListener(event: "test:coverage", listener: (data: TestCoverage) => void): this; - prependListener(event: "test:complete", listener: (data: TestComplete) => void): this; - prependListener(event: "test:dequeue", listener: (data: TestDequeue) => void): this; - prependListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; - prependListener(event: "test:enqueue", listener: (data: TestEnqueue) => void): this; - prependListener(event: "test:fail", listener: (data: TestFail) => void): this; - prependListener(event: "test:pass", listener: (data: TestPass) => void): this; - prependListener(event: "test:plan", listener: (data: TestPlan) => void): this; - prependListener(event: "test:start", listener: (data: TestStart) => void): this; - prependListener(event: "test:stderr", listener: (data: TestStderr) => void): this; - prependListener(event: "test:stdout", listener: (data: TestStdout) => void): this; - prependListener(event: "test:watch:drained", listener: () => void): this; - prependListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: "test:coverage", listener: (data: TestCoverage) => void): this; - prependOnceListener(event: "test:complete", listener: (data: TestComplete) => void): this; - prependOnceListener(event: "test:dequeue", listener: (data: TestDequeue) => void): this; - prependOnceListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; - prependOnceListener(event: "test:enqueue", listener: (data: TestEnqueue) => void): this; - prependOnceListener(event: "test:fail", listener: (data: TestFail) => void): this; - prependOnceListener(event: "test:pass", listener: (data: TestPass) => void): this; - prependOnceListener(event: "test:plan", listener: (data: TestPlan) => void): this; - prependOnceListener(event: "test:start", listener: (data: TestStart) => void): this; - prependOnceListener(event: "test:stderr", listener: (data: TestStderr) => void): this; - prependOnceListener(event: "test:stdout", listener: (data: TestStdout) => void): this; - prependOnceListener(event: "test:watch:drained", listener: () => void): this; - prependOnceListener(event: string, listener: (...args: any[]) => void): this; - } - /** - * An instance of `TestContext` is passed to each test function in order to - * interact with the test runner. However, the `TestContext` constructor is not - * exposed as part of the API. - * @since v18.0.0, v16.17.0 - */ - class TestContext { - /** - * An object containing assertion methods bound to the test context. - * The top-level functions from the `node:assert` module are exposed here for the purpose of creating test plans. - * @since v22.2.0, v20.15.0 - */ - readonly assert: TestContextAssert; - /** - * This function is used to create a hook running before subtest of the current test. - * @param fn The hook function. The first argument to this function is a `TestContext` object. - * If the hook uses callbacks, the callback function is passed as the second argument. - * @param options Configuration options for the hook. - * @since v20.1.0, v18.17.0 - */ - before(fn?: TestContextHookFn, options?: HookOptions): void; - /** - * This function is used to create a hook running before each subtest of the current test. - * @param fn The hook function. The first argument to this function is a `TestContext` object. - * If the hook uses callbacks, the callback function is passed as the second argument. - * @param options Configuration options for the hook. - * @since v18.8.0 - */ - beforeEach(fn?: TestContextHookFn, options?: HookOptions): void; - /** - * This function is used to create a hook that runs after the current test finishes. - * @param fn The hook function. The first argument to this function is a `TestContext` object. - * If the hook uses callbacks, the callback function is passed as the second argument. - * @param options Configuration options for the hook. - * @since v18.13.0 + * The type of a function passed to {@link test}. The first argument to this function is a {@link TestContext} object. + * If the test uses callbacks, the callback function is passed as the second argument. */ - after(fn?: TestContextHookFn, options?: HookOptions): void; + type TestFn = (t: TestContext, done: (result?: any) => void) => void | Promise; /** - * This function is used to create a hook running after each subtest of the current test. - * @param fn The hook function. The first argument to this function is a `TestContext` object. - * If the hook uses callbacks, the callback function is passed as the second argument. - * @param options Configuration options for the hook. - * @since v18.8.0 + * The type of a suite test function. The argument to this function is a {@link SuiteContext} object. */ - afterEach(fn?: TestContextHookFn, options?: HookOptions): void; + type SuiteFn = (s: SuiteContext) => void | Promise; + interface TestShard { + /** + * A positive integer between 1 and `total` that specifies the index of the shard to run. + */ + index: number; + /** + * A positive integer that specifies the total number of shards to split the test files to. + */ + total: number; + } + interface RunOptions { + /** + * If a number is provided, then that many test processes would run in parallel, where each process corresponds to one test file. + * If `true`, it would run `os.availableParallelism() - 1` test files in parallel. If `false`, it would only run one test file at a time. + * @default false + */ + concurrency?: number | boolean | undefined; + /** + * An array containing the list of files to run. If omitted, files are run according to the + * [test runner execution model](https://nodejs.org/docs/latest-v22.x/api/test.html#test-runner-execution-model). + */ + files?: readonly string[] | undefined; + /** + * Configures the test runner to exit the process once all known + * tests have finished executing even if the event loop would + * otherwise remain active. + * @default false + */ + forceExit?: boolean | undefined; + /** + * An array containing the list of glob patterns to match test files. + * This option cannot be used together with `files`. If omitted, files are run according to the + * [test runner execution model](https://nodejs.org/docs/latest-v22.x/api/test.html#test-runner-execution-model). + * @since v22.6.0 + */ + globPatterns?: readonly string[] | undefined; + /** + * Sets inspector port of test child process. + * This can be a number, or a function that takes no arguments and returns a + * number. If a nullish value is provided, each process gets its own port, + * incremented from the primary's `process.debugPort`. This option is ignored + * if the `isolation` option is set to `'none'` as no child processes are + * spawned. + * @default undefined + */ + inspectPort?: number | (() => number) | undefined; + /** + * Configures the type of test isolation. If set to + * `'process'`, each test file is run in a separate child process. If set to + * `'none'`, all test files run in the current process. + * @default 'process' + * @since v22.8.0 + */ + isolation?: "process" | "none" | undefined; + /** + * If truthy, the test context will only run tests that have the `only` option set + */ + only?: boolean | undefined; + /** + * A function that accepts the `TestsStream` instance and can be used to setup listeners before any tests are run. + * @default undefined + */ + setup?: ((reporter: TestsStream) => void | Promise) | undefined; + /** + * An array of CLI flags to pass to the `node` executable when + * spawning the subprocesses. This option has no effect when `isolation` is `'none`'. + * @since v22.10.0 + * @default [] + */ + execArgv?: readonly string[] | undefined; + /** + * An array of CLI flags to pass to each test file when spawning the + * subprocesses. This option has no effect when `isolation` is `'none'`. + * @since v22.10.0 + * @default [] + */ + argv?: readonly string[] | undefined; + /** + * Allows aborting an in-progress test execution. + */ + signal?: AbortSignal | undefined; + /** + * If provided, only run tests whose name matches the provided pattern. + * Strings are interpreted as JavaScript regular expressions. + * @default undefined + */ + testNamePatterns?: string | RegExp | ReadonlyArray | undefined; + /** + * A String, RegExp or a RegExp Array, that can be used to exclude running tests whose + * name matches the provided pattern. Test name patterns are interpreted as JavaScript + * regular expressions. For each test that is executed, any corresponding test hooks, + * such as `beforeEach()`, are also run. + * @default undefined + * @since v22.1.0 + */ + testSkipPatterns?: string | RegExp | ReadonlyArray | undefined; + /** + * The number of milliseconds after which the test execution will fail. + * If unspecified, subtests inherit this value from their parent. + * @default Infinity + */ + timeout?: number | undefined; + /** + * Whether to run in watch mode or not. + * @default false + */ + watch?: boolean | undefined; + /** + * Running tests in a specific shard. + * @default undefined + */ + shard?: TestShard | undefined; + /** + * enable [code coverage](https://nodejs.org/docs/latest-v22.x/api/test.html#collecting-code-coverage) collection. + * @since v22.10.0 + * @default false + */ + coverage?: boolean | undefined; + /** + * Excludes specific files from code coverage + * using a glob pattern, which can match both absolute and relative file paths. + * This property is only applicable when `coverage` was set to `true`. + * If both `coverageExcludeGlobs` and `coverageIncludeGlobs` are provided, + * files must meet **both** criteria to be included in the coverage report. + * @since v22.10.0 + * @default undefined + */ + coverageExcludeGlobs?: string | readonly string[] | undefined; + /** + * Includes specific files in code coverage + * using a glob pattern, which can match both absolute and relative file paths. + * This property is only applicable when `coverage` was set to `true`. + * If both `coverageExcludeGlobs` and `coverageIncludeGlobs` are provided, + * files must meet **both** criteria to be included in the coverage report. + * @since v22.10.0 + * @default undefined + */ + coverageIncludeGlobs?: string | readonly string[] | undefined; + /** + * Require a minimum percent of covered lines. If code + * coverage does not reach the threshold specified, the process will exit with code `1`. + * @since v22.10.0 + * @default 0 + */ + lineCoverage?: number | undefined; + /** + * Require a minimum percent of covered branches. If code + * coverage does not reach the threshold specified, the process will exit with code `1`. + * @since v22.10.0 + * @default 0 + */ + branchCoverage?: number | undefined; + /** + * Require a minimum percent of covered functions. If code + * coverage does not reach the threshold specified, the process will exit with code `1`. + * @since v22.10.0 + * @default 0 + */ + functionCoverage?: number | undefined; + } + /** + * A successful call to `run()` will return a new `TestsStream` object, streaming a series of events representing the execution of the tests. + * + * Some of the events are guaranteed to be emitted in the same order as the tests are defined, while others are emitted in the order that the tests execute. + * @since v18.9.0, v16.19.0 + */ + interface TestsStream extends Readable { + addListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this; + addListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this; + addListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this; + addListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this; + addListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this; + addListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this; + addListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this; + addListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this; + addListener(event: "test:start", listener: (data: EventData.TestStart) => void): this; + addListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this; + addListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this; + addListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this; + addListener(event: "test:watch:drained", listener: () => void): this; + addListener(event: string, listener: (...args: any[]) => void): this; + emit(event: "test:coverage", data: EventData.TestCoverage): boolean; + emit(event: "test:complete", data: EventData.TestComplete): boolean; + emit(event: "test:dequeue", data: EventData.TestDequeue): boolean; + emit(event: "test:diagnostic", data: EventData.TestDiagnostic): boolean; + emit(event: "test:enqueue", data: EventData.TestEnqueue): boolean; + emit(event: "test:fail", data: EventData.TestFail): boolean; + emit(event: "test:pass", data: EventData.TestPass): boolean; + emit(event: "test:plan", data: EventData.TestPlan): boolean; + emit(event: "test:start", data: EventData.TestStart): boolean; + emit(event: "test:stderr", data: EventData.TestStderr): boolean; + emit(event: "test:stdout", data: EventData.TestStdout): boolean; + emit(event: "test:summary", data: EventData.TestSummary): boolean; + emit(event: "test:watch:drained"): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this; + on(event: "test:complete", listener: (data: EventData.TestComplete) => void): this; + on(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this; + on(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this; + on(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this; + on(event: "test:fail", listener: (data: EventData.TestFail) => void): this; + on(event: "test:pass", listener: (data: EventData.TestPass) => void): this; + on(event: "test:plan", listener: (data: EventData.TestPlan) => void): this; + on(event: "test:start", listener: (data: EventData.TestStart) => void): this; + on(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this; + on(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this; + on(event: "test:summary", listener: (data: EventData.TestSummary) => void): this; + on(event: "test:watch:drained", listener: () => void): this; + on(event: string, listener: (...args: any[]) => void): this; + once(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this; + once(event: "test:complete", listener: (data: EventData.TestComplete) => void): this; + once(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this; + once(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this; + once(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this; + once(event: "test:fail", listener: (data: EventData.TestFail) => void): this; + once(event: "test:pass", listener: (data: EventData.TestPass) => void): this; + once(event: "test:plan", listener: (data: EventData.TestPlan) => void): this; + once(event: "test:start", listener: (data: EventData.TestStart) => void): this; + once(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this; + once(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this; + once(event: "test:summary", listener: (data: EventData.TestSummary) => void): this; + once(event: "test:watch:drained", listener: () => void): this; + once(event: string, listener: (...args: any[]) => void): this; + prependListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this; + prependListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this; + prependListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this; + prependListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this; + prependListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this; + prependListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this; + prependListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this; + prependListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this; + prependListener(event: "test:start", listener: (data: EventData.TestStart) => void): this; + prependListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this; + prependListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this; + prependListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this; + prependListener(event: "test:watch:drained", listener: () => void): this; + prependListener(event: string, listener: (...args: any[]) => void): this; + prependOnceListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this; + prependOnceListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this; + prependOnceListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this; + prependOnceListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this; + prependOnceListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this; + prependOnceListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this; + prependOnceListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this; + prependOnceListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this; + prependOnceListener(event: "test:start", listener: (data: EventData.TestStart) => void): this; + prependOnceListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this; + prependOnceListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this; + prependOnceListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this; + prependOnceListener(event: "test:watch:drained", listener: () => void): this; + prependOnceListener(event: string, listener: (...args: any[]) => void): this; + } + namespace EventData { + interface Error extends globalThis.Error { + cause: globalThis.Error; + } + interface LocationInfo { + /** + * The column number where the test is defined, or + * `undefined` if the test was run through the REPL. + */ + column?: number; + /** + * The path of the test file, `undefined` if test was run through the REPL. + */ + file?: string; + /** + * The line number where the test is defined, or `undefined` if the test was run through the REPL. + */ + line?: number; + } + interface TestDiagnostic extends LocationInfo { + /** + * The diagnostic message. + */ + message: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The severity level of the diagnostic message. + * Possible values are: + * * `'info'`: Informational messages. + * * `'warn'`: Warnings. + * * `'error'`: Errors. + */ + level: "info" | "warn" | "error"; + } + interface TestCoverage { + /** + * An object containing the coverage report. + */ + summary: { + /** + * An array of coverage reports for individual files. + */ + files: Array<{ + /** + * The absolute path of the file. + */ + path: string; + /** + * The total number of lines. + */ + totalLineCount: number; + /** + * The total number of branches. + */ + totalBranchCount: number; + /** + * The total number of functions. + */ + totalFunctionCount: number; + /** + * The number of covered lines. + */ + coveredLineCount: number; + /** + * The number of covered branches. + */ + coveredBranchCount: number; + /** + * The number of covered functions. + */ + coveredFunctionCount: number; + /** + * The percentage of lines covered. + */ + coveredLinePercent: number; + /** + * The percentage of branches covered. + */ + coveredBranchPercent: number; + /** + * The percentage of functions covered. + */ + coveredFunctionPercent: number; + /** + * An array of functions representing function coverage. + */ + functions: Array<{ + /** + * The name of the function. + */ + name: string; + /** + * The line number where the function is defined. + */ + line: number; + /** + * The number of times the function was called. + */ + count: number; + }>; + /** + * An array of branches representing branch coverage. + */ + branches: Array<{ + /** + * The line number where the branch is defined. + */ + line: number; + /** + * The number of times the branch was taken. + */ + count: number; + }>; + /** + * An array of lines representing line numbers and the number of times they were covered. + */ + lines: Array<{ + /** + * The line number. + */ + line: number; + /** + * The number of times the line was covered. + */ + count: number; + }>; + }>; + /** + * An object containing whether or not the coverage for + * each coverage type. + * @since v22.9.0 + */ + thresholds: { + /** + * The function coverage threshold. + */ + function: number; + /** + * The branch coverage threshold. + */ + branch: number; + /** + * The line coverage threshold. + */ + line: number; + }; + /** + * An object containing a summary of coverage for all files. + */ + totals: { + /** + * The total number of lines. + */ + totalLineCount: number; + /** + * The total number of branches. + */ + totalBranchCount: number; + /** + * The total number of functions. + */ + totalFunctionCount: number; + /** + * The number of covered lines. + */ + coveredLineCount: number; + /** + * The number of covered branches. + */ + coveredBranchCount: number; + /** + * The number of covered functions. + */ + coveredFunctionCount: number; + /** + * The percentage of lines covered. + */ + coveredLinePercent: number; + /** + * The percentage of branches covered. + */ + coveredBranchPercent: number; + /** + * The percentage of functions covered. + */ + coveredFunctionPercent: number; + }; + /** + * The working directory when code coverage began. This + * is useful for displaying relative path names in case + * the tests changed the working directory of the Node.js process. + */ + workingDirectory: string; + }; + /** + * The nesting level of the test. + */ + nesting: number; + } + interface TestComplete extends LocationInfo { + /** + * Additional execution metadata. + */ + details: { + /** + * Whether the test passed or not. + */ + passed: boolean; + /** + * The duration of the test in milliseconds. + */ + duration_ms: number; + /** + * An error wrapping the error thrown by the test if it did not pass. + */ + error?: Error; + /** + * The type of the test, used to denote whether this is a suite. + */ + type?: "suite"; + }; + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The ordinal number of the test. + */ + testNumber: number; + /** + * Present if `context.todo` is called. + */ + todo?: string | boolean; + /** + * Present if `context.skip` is called. + */ + skip?: string | boolean; + } + interface TestDequeue extends LocationInfo { + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The test type. Either `'suite'` or `'test'`. + * @since v22.15.0 + */ + type: "suite" | "test"; + } + interface TestEnqueue extends LocationInfo { + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The test type. Either `'suite'` or `'test'`. + * @since v22.15.0 + */ + type: "suite" | "test"; + } + interface TestFail extends LocationInfo { + /** + * Additional execution metadata. + */ + details: { + /** + * The duration of the test in milliseconds. + */ + duration_ms: number; + /** + * An error wrapping the error thrown by the test. + */ + error: Error; + /** + * The type of the test, used to denote whether this is a suite. + * @since v20.0.0, v19.9.0, v18.17.0 + */ + type?: "suite"; + }; + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The ordinal number of the test. + */ + testNumber: number; + /** + * Present if `context.todo` is called. + */ + todo?: string | boolean; + /** + * Present if `context.skip` is called. + */ + skip?: string | boolean; + } + interface TestPass extends LocationInfo { + /** + * Additional execution metadata. + */ + details: { + /** + * The duration of the test in milliseconds. + */ + duration_ms: number; + /** + * The type of the test, used to denote whether this is a suite. + * @since 20.0.0, 19.9.0, 18.17.0 + */ + type?: "suite"; + }; + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The ordinal number of the test. + */ + testNumber: number; + /** + * Present if `context.todo` is called. + */ + todo?: string | boolean; + /** + * Present if `context.skip` is called. + */ + skip?: string | boolean; + } + interface TestPlan extends LocationInfo { + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The number of subtests that have ran. + */ + count: number; + } + interface TestStart extends LocationInfo { + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + } + interface TestStderr { + /** + * The path of the test file. + */ + file: string; + /** + * The message written to `stderr`. + */ + message: string; + } + interface TestStdout { + /** + * The path of the test file. + */ + file: string; + /** + * The message written to `stdout`. + */ + message: string; + } + interface TestSummary { + /** + * An object containing the counts of various test results. + */ + counts: { + /** + * The total number of cancelled tests. + */ + cancelled: number; + /** + * The total number of passed tests. + */ + passed: number; + /** + * The total number of skipped tests. + */ + skipped: number; + /** + * The total number of suites run. + */ + suites: number; + /** + * The total number of tests run, excluding suites. + */ + tests: number; + /** + * The total number of TODO tests. + */ + todo: number; + /** + * The total number of top level tests and suites. + */ + topLevel: number; + }; + /** + * The duration of the test run in milliseconds. + */ + duration_ms: number; + /** + * The path of the test file that generated the + * summary. If the summary corresponds to multiple files, this value is + * `undefined`. + */ + file: string | undefined; + /** + * Indicates whether or not the test run is considered + * successful or not. If any error condition occurs, such as a failing test or + * unmet coverage threshold, this value will be set to `false`. + */ + success: boolean; + } + } /** - * This function is used to write diagnostics to the output. Any diagnostic - * information is included at the end of the test's results. This function does - * not return a value. - * - * ```js - * test('top level test', (t) => { - * t.diagnostic('A diagnostic message'); - * }); - * ``` + * An instance of `TestContext` is passed to each test function in order to + * interact with the test runner. However, the `TestContext` constructor is not + * exposed as part of the API. * @since v18.0.0, v16.17.0 - * @param message Message to be reported. - */ - diagnostic(message: string): void; - /** - * The absolute path of the test file that created the current test. If a test file imports - * additional modules that generate tests, the imported tests will return the path of the root test file. - * @since v22.6.0 */ - readonly filePath: string | undefined; - /** - * The name of the test and each of its ancestors, separated by `>`. - * @since v22.3.0 - */ - readonly fullName: string; - /** - * The name of the test. - * @since v18.8.0, v16.18.0 - */ - readonly name: string; - /** - * Used to set the number of assertions and subtests that are expected to run within the test. - * If the number of assertions and subtests that run does not match the expected count, the test will fail. - * - * To make sure assertions are tracked, the assert functions on `context.assert` must be used, - * instead of importing from the `node:assert` module. - * ```js - * test('top level test', (t) => { - * t.plan(2); - * t.assert.ok('some relevant assertion here'); - * t.test('subtest', () => {}); - * }); - * ``` - * - * When working with asynchronous code, the `plan` function can be used to ensure that the correct number of assertions are run: - * ```js - * test('planning with streams', (t, done) => { - * function* generate() { - * yield 'a'; - * yield 'b'; - * yield 'c'; - * } - * const expected = ['a', 'b', 'c']; - * t.plan(expected.length); - * const stream = Readable.from(generate()); - * stream.on('data', (chunk) => { - * t.assert.strictEqual(chunk, expected.shift()); - * }); - * stream.on('end', () => { - * done(); - * }); - * }); - * ``` - * @since v22.2.0 - */ - plan(count: number): void; - /** - * If `shouldRunOnlyTests` is truthy, the test context will only run tests that - * have the `only` option set. Otherwise, all tests are run. If Node.js was not - * started with the `--test-only` command-line option, this function is a - * no-op. - * - * ```js - * test('top level test', (t) => { - * // The test context can be set to run subtests with the 'only' option. - * t.runOnly(true); - * return Promise.all([ - * t.test('this subtest is now skipped'), - * t.test('this subtest is run', { only: true }), - * ]); - * }); - * ``` - * @since v18.0.0, v16.17.0 - * @param shouldRunOnlyTests Whether or not to run `only` tests. - */ - runOnly(shouldRunOnlyTests: boolean): void; - /** - * ```js - * test('top level test', async (t) => { - * await fetch('some/uri', { signal: t.signal }); - * }); - * ``` - * @since v18.7.0, v16.17.0 - */ - readonly signal: AbortSignal; - /** - * This function causes the test's output to indicate the test as skipped. If `message` is provided, it is included in the output. Calling `skip()` does - * not terminate execution of the test function. This function does not return a - * value. - * - * ```js - * test('top level test', (t) => { - * // Make sure to return here as well if the test contains additional logic. - * t.skip('this is skipped'); - * }); - * ``` - * @since v18.0.0, v16.17.0 - * @param message Optional skip message. - */ - skip(message?: string): void; - /** - * This function adds a `TODO` directive to the test's output. If `message` is - * provided, it is included in the output. Calling `todo()` does not terminate - * execution of the test function. This function does not return a value. - * - * ```js - * test('top level test', (t) => { - * // This test is marked as `TODO` - * t.todo('this is a todo'); - * }); - * ``` - * @since v18.0.0, v16.17.0 - * @param message Optional `TODO` message. - */ - todo(message?: string): void; - /** - * This function is used to create subtests under the current test. This function behaves in - * the same fashion as the top level {@link test} function. - * @since v18.0.0 - * @param name The name of the test, which is displayed when reporting test results. - * Defaults to the `name` property of `fn`, or `''` if `fn` does not have a name. - * @param options Configuration options for the test. - * @param fn The function under test. This first argument to this function is a {@link TestContext} object. - * If the test uses callbacks, the callback function is passed as the second argument. - * @returns A {@link Promise} resolved with `undefined` once the test completes. - */ - test: typeof test; - /** - * Each test provides its own MockTracker instance. - */ - readonly mock: MockTracker; - } - interface TestContextAssert { - /** - * Identical to the `deepEqual` function from the `node:assert` module, but bound to the test context. - */ - deepEqual: typeof import("node:assert").deepEqual; - /** - * Identical to the `deepStrictEqual` function from the `node:assert` module, but bound to the test context. - * - * **Note:** as this method returns a type assertion, the context parameter in the callback signature must have a - * type annotation, otherwise an error will be raised by the TypeScript compiler: - * ```ts - * import { test, type TestContext } from 'node:test'; - * - * // The test function's context parameter must have a type annotation. - * test('example', (t: TestContext) => { - * t.assert.deepStrictEqual(actual, expected); - * }); - * - * // Omitting the type annotation will result in a compilation error. - * test('example', t => { - * t.assert.deepStrictEqual(actual, expected); // Error: 't' needs an explicit type annotation. - * }); - * ``` - */ - deepStrictEqual: typeof import("node:assert").deepStrictEqual; - /** - * Identical to the `doesNotMatch` function from the `node:assert` module, but bound to the test context. - */ - doesNotMatch: typeof import("node:assert").doesNotMatch; - /** - * Identical to the `doesNotReject` function from the `node:assert` module, but bound to the test context. - */ - doesNotReject: typeof import("node:assert").doesNotReject; - /** - * Identical to the `doesNotThrow` function from the `node:assert` module, but bound to the test context. - */ - doesNotThrow: typeof import("node:assert").doesNotThrow; - /** - * Identical to the `equal` function from the `node:assert` module, but bound to the test context. - */ - equal: typeof import("node:assert").equal; - /** - * Identical to the `fail` function from the `node:assert` module, but bound to the test context. - */ - fail: typeof import("node:assert").fail; - /** - * Identical to the `ifError` function from the `node:assert` module, but bound to the test context. - * - * **Note:** as this method returns a type assertion, the context parameter in the callback signature must have a - * type annotation, otherwise an error will be raised by the TypeScript compiler: - * ```ts - * import { test, type TestContext } from 'node:test'; - * - * // The test function's context parameter must have a type annotation. - * test('example', (t: TestContext) => { - * t.assert.ifError(err); - * }); - * - * // Omitting the type annotation will result in a compilation error. - * test('example', t => { - * t.assert.ifError(err); // Error: 't' needs an explicit type annotation. - * }); - * ``` - */ - ifError: typeof import("node:assert").ifError; - /** - * Identical to the `match` function from the `node:assert` module, but bound to the test context. - */ - match: typeof import("node:assert").match; - /** - * Identical to the `notDeepEqual` function from the `node:assert` module, but bound to the test context. - */ - notDeepEqual: typeof import("node:assert").notDeepEqual; - /** - * Identical to the `notDeepStrictEqual` function from the `node:assert` module, but bound to the test context. - */ - notDeepStrictEqual: typeof import("node:assert").notDeepStrictEqual; - /** - * Identical to the `notEqual` function from the `node:assert` module, but bound to the test context. - */ - notEqual: typeof import("node:assert").notEqual; - /** - * Identical to the `notStrictEqual` function from the `node:assert` module, but bound to the test context. - */ - notStrictEqual: typeof import("node:assert").notStrictEqual; - /** - * Identical to the `ok` function from the `node:assert` module, but bound to the test context. - * - * **Note:** as this method returns a type assertion, the context parameter in the callback signature must have a - * type annotation, otherwise an error will be raised by the TypeScript compiler: - * ```ts - * import { test, type TestContext } from 'node:test'; - * - * // The test function's context parameter must have a type annotation. - * test('example', (t: TestContext) => { - * t.assert.ok(condition); - * }); - * - * // Omitting the type annotation will result in a compilation error. - * test('example', t => { - * t.assert.ok(condition)); // Error: 't' needs an explicit type annotation. - * }); - * ``` - */ - ok: typeof import("node:assert").ok; - /** - * Identical to the `rejects` function from the `node:assert` module, but bound to the test context. - */ - rejects: typeof import("node:assert").rejects; - /** - * Identical to the `strictEqual` function from the `node:assert` module, but bound to the test context. - * - * **Note:** as this method returns a type assertion, the context parameter in the callback signature must have a - * type annotation, otherwise an error will be raised by the TypeScript compiler: - * ```ts - * import { test, type TestContext } from 'node:test'; - * - * // The test function's context parameter must have a type annotation. - * test('example', (t: TestContext) => { - * t.assert.strictEqual(actual, expected); - * }); - * - * // Omitting the type annotation will result in a compilation error. - * test('example', t => { - * t.assert.strictEqual(actual, expected); // Error: 't' needs an explicit type annotation. - * }); - * ``` - */ - strictEqual: typeof import("node:assert").strictEqual; - /** - * Identical to the `throws` function from the `node:assert` module, but bound to the test context. - */ - throws: typeof import("node:assert").throws; - /** - * This function implements assertions for snapshot testing. - * ```js - * test('snapshot test with default serialization', (t) => { - * t.assert.snapshot({ value1: 1, value2: 2 }); - * }); - * - * test('snapshot test with custom serialization', (t) => { - * t.assert.snapshot({ value3: 3, value4: 4 }, { - * serializers: [(value) => JSON.stringify(value)] - * }); - * }); - * ``` - * - * Only available through the [--experimental-test-snapshots](https://nodejs.org/api/cli.html#--experimental-test-snapshots) flag. - * @since v22.3.0 - * @experimental - */ - snapshot(value: any, options?: AssertSnapshotOptions): void; - } - interface AssertSnapshotOptions { - /** - * An array of synchronous functions used to serialize `value` into a string. - * `value` is passed as the only argument to the first serializer function. - * The return value of each serializer is passed as input to the next serializer. - * Once all serializers have run, the resulting value is coerced to a string. - * - * If no serializers are provided, the test runner's default serializers are used. - */ - serializers?: ReadonlyArray<(value: any) => any> | undefined; - } - - /** - * An instance of `SuiteContext` is passed to each suite function in order to - * interact with the test runner. However, the `SuiteContext` constructor is not - * exposed as part of the API. - * @since v18.7.0, v16.17.0 - */ - class SuiteContext { - /** - * The absolute path of the test file that created the current suite. If a test file imports - * additional modules that generate suites, the imported suites will return the path of the root test file. - * @since v22.6.0 - */ - readonly filePath: string | undefined; - /** - * The name of the suite. - * @since v18.8.0, v16.18.0 - */ - readonly name: string; - /** - * Can be used to abort test subtasks when the test has been aborted. - * @since v18.7.0, v16.17.0 - */ - readonly signal: AbortSignal; - } - interface TestOptions { - /** - * If a number is provided, then that many tests would run in parallel. - * If truthy, it would run (number of cpu cores - 1) tests in parallel. - * For subtests, it will be `Infinity` tests in parallel. - * If falsy, it would only run one test at a time. - * If unspecified, subtests inherit this value from their parent. - * @default false - */ - concurrency?: number | boolean | undefined; - /** - * If truthy, and the test context is configured to run `only` tests, then this test will be - * run. Otherwise, the test is skipped. - * @default false - */ - only?: boolean | undefined; - /** - * Allows aborting an in-progress test. - * @since v18.8.0 - */ - signal?: AbortSignal | undefined; - /** - * If truthy, the test is skipped. If a string is provided, that string is displayed in the - * test results as the reason for skipping the test. - * @default false - */ - skip?: boolean | string | undefined; - /** - * A number of milliseconds the test will fail after. If unspecified, subtests inherit this - * value from their parent. - * @default Infinity - * @since v18.7.0 - */ - timeout?: number | undefined; - /** - * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in - * the test results as the reason why the test is `TODO`. - * @default false - */ - todo?: boolean | string | undefined; - /** - * The number of assertions and subtests expected to be run in the test. - * If the number of assertions run in the test does not match the number - * specified in the plan, the test will fail. - * @default undefined - * @since v22.2.0 - */ - plan?: number | undefined; - } - /** - * This function creates a hook that runs before executing a suite. - * - * ```js - * describe('tests', async () => { - * before(() => console.log('about to run some test')); - * it('is a subtest', () => { - * assert.ok('some relevant assertion here'); - * }); - * }); - * ``` - * @since v18.8.0, v16.18.0 - * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument. - * @param options Configuration options for the hook. - */ - function before(fn?: HookFn, options?: HookOptions): void; - /** - * This function creates a hook that runs after executing a suite. - * - * ```js - * describe('tests', async () => { - * after(() => console.log('finished running tests')); - * it('is a subtest', () => { - * assert.ok('some relevant assertion here'); - * }); - * }); - * ``` - * @since v18.8.0, v16.18.0 - * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument. - * @param options Configuration options for the hook. - */ - function after(fn?: HookFn, options?: HookOptions): void; - /** - * This function creates a hook that runs before each test in the current suite. - * - * ```js - * describe('tests', async () => { - * beforeEach(() => console.log('about to run a test')); - * it('is a subtest', () => { - * assert.ok('some relevant assertion here'); - * }); - * }); - * ``` - * @since v18.8.0, v16.18.0 - * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument. - * @param options Configuration options for the hook. - */ - function beforeEach(fn?: HookFn, options?: HookOptions): void; - /** - * This function creates a hook that runs after each test in the current suite. - * The `afterEach()` hook is run even if the test fails. - * - * ```js - * describe('tests', async () => { - * afterEach(() => console.log('finished running a test')); - * it('is a subtest', () => { - * assert.ok('some relevant assertion here'); - * }); - * }); - * ``` - * @since v18.8.0, v16.18.0 - * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument. - * @param options Configuration options for the hook. - */ - function afterEach(fn?: HookFn, options?: HookOptions): void; - /** - * The hook function. The first argument is the context in which the hook is called. - * If the hook uses callbacks, the callback function is passed as the second argument. - */ - type HookFn = (c: TestContext | SuiteContext, done: (result?: any) => void) => any; - /** - * The hook function. The first argument is a `TestContext` object. - * If the hook uses callbacks, the callback function is passed as the second argument. - */ - type TestContextHookFn = (t: TestContext, done: (result?: any) => void) => any; - /** - * Configuration options for hooks. - * @since v18.8.0 - */ - interface HookOptions { - /** - * Allows aborting an in-progress hook. - */ - signal?: AbortSignal | undefined; - /** - * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this - * value from their parent. - * @default Infinity - */ - timeout?: number | undefined; - } - interface MockFunctionOptions { - /** - * The number of times that the mock will use the behavior of `implementation`. - * Once the mock function has been called `times` times, - * it will automatically restore the behavior of `original`. - * This value must be an integer greater than zero. - * @default Infinity - */ - times?: number | undefined; - } - interface MockMethodOptions extends MockFunctionOptions { - /** - * If `true`, `object[methodName]` is treated as a getter. - * This option cannot be used with the `setter` option. - */ - getter?: boolean | undefined; - /** - * If `true`, `object[methodName]` is treated as a setter. - * This option cannot be used with the `getter` option. - */ - setter?: boolean | undefined; - } - type Mock = F & { - mock: MockFunctionContext; - }; - type NoOpFunction = (...args: any[]) => undefined; - type FunctionPropertyNames = { - [K in keyof T]: T[K] extends Function ? K : never; - }[keyof T]; - interface MockModuleOptions { - /** - * If false, each call to `require()` or `import()` generates a new mock module. - * If true, subsequent calls will return the same module mock, and the mock module is inserted into the CommonJS cache. - * @default false - */ - cache?: boolean | undefined; - /** - * The value to use as the mocked module's default export. - * - * If this value is not provided, ESM mocks do not include a default export. - * If the mock is a CommonJS or builtin module, this setting is used as the value of `module.exports`. - * If this value is not provided, CJS and builtin mocks use an empty object as the value of `module.exports`. - */ - defaultExport?: any; - /** - * An object whose keys and values are used to create the named exports of the mock module. - * - * If the mock is a CommonJS or builtin module, these values are copied onto `module.exports`. - * Therefore, if a mock is created with both named exports and a non-object default export, - * the mock will throw an exception when used as a CJS or builtin module. - */ - namedExports?: object | undefined; - } - /** - * The `MockTracker` class is used to manage mocking functionality. The test runner - * module provides a top level `mock` export which is a `MockTracker` instance. - * Each test also provides its own `MockTracker` instance via the test context's `mock` property. - * @since v19.1.0, v18.13.0 - */ - class MockTracker { - /** - * This function is used to create a mock function. - * - * The following example creates a mock function that increments a counter by one - * on each invocation. The `times` option is used to modify the mock behavior such - * that the first two invocations add two to the counter instead of one. - * - * ```js - * test('mocks a counting function', (t) => { - * let cnt = 0; - * - * function addOne() { - * cnt++; - * return cnt; - * } - * - * function addTwo() { - * cnt += 2; - * return cnt; - * } - * - * const fn = t.mock.fn(addOne, addTwo, { times: 2 }); - * - * assert.strictEqual(fn(), 2); - * assert.strictEqual(fn(), 4); - * assert.strictEqual(fn(), 5); - * assert.strictEqual(fn(), 6); - * }); - * ``` - * @since v19.1.0, v18.13.0 - * @param original An optional function to create a mock on. - * @param implementation An optional function used as the mock implementation for `original`. This is useful for creating mocks that exhibit one behavior for a specified number of calls and - * then restore the behavior of `original`. - * @param options Optional configuration options for the mock function. - * @return The mocked function. The mocked function contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the - * behavior of the mocked function. - */ - fn(original?: F, options?: MockFunctionOptions): Mock; - fn( - original?: F, - implementation?: Implementation, - options?: MockFunctionOptions, - ): Mock; - /** - * This function is used to create a mock on an existing object method. The - * following example demonstrates how a mock is created on an existing object - * method. - * - * ```js - * test('spies on an object method', (t) => { - * const number = { - * value: 5, - * subtract(a) { - * return this.value - a; - * }, - * }; - * - * t.mock.method(number, 'subtract'); - * assert.strictEqual(number.subtract.mock.calls.length, 0); - * assert.strictEqual(number.subtract(3), 2); - * assert.strictEqual(number.subtract.mock.calls.length, 1); - * - * const call = number.subtract.mock.calls[0]; - * - * assert.deepStrictEqual(call.arguments, [3]); - * assert.strictEqual(call.result, 2); - * assert.strictEqual(call.error, undefined); - * assert.strictEqual(call.target, undefined); - * assert.strictEqual(call.this, number); - * }); - * ``` - * @since v19.1.0, v18.13.0 - * @param object The object whose method is being mocked. - * @param methodName The identifier of the method on `object` to mock. If `object[methodName]` is not a function, an error is thrown. - * @param implementation An optional function used as the mock implementation for `object[methodName]`. - * @param options Optional configuration options for the mock method. - * @return The mocked method. The mocked method contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the - * behavior of the mocked method. - */ - method< - MockedObject extends object, - MethodName extends FunctionPropertyNames, - >( - object: MockedObject, - methodName: MethodName, - options?: MockFunctionOptions, - ): MockedObject[MethodName] extends Function ? Mock - : never; - method< - MockedObject extends object, - MethodName extends FunctionPropertyNames, - Implementation extends Function, - >( - object: MockedObject, - methodName: MethodName, - implementation: Implementation, - options?: MockFunctionOptions, - ): MockedObject[MethodName] extends Function ? Mock - : never; - method( - object: MockedObject, - methodName: keyof MockedObject, - options: MockMethodOptions, - ): Mock; - method( - object: MockedObject, - methodName: keyof MockedObject, - implementation: Function, - options: MockMethodOptions, - ): Mock; - - /** - * This function is syntax sugar for `MockTracker.method` with `options.getter` set to `true`. - * @since v19.3.0, v18.13.0 - */ - getter< - MockedObject extends object, - MethodName extends keyof MockedObject, - >( - object: MockedObject, - methodName: MethodName, - options?: MockFunctionOptions, - ): Mock<() => MockedObject[MethodName]>; - getter< - MockedObject extends object, - MethodName extends keyof MockedObject, - Implementation extends Function, - >( - object: MockedObject, - methodName: MethodName, - implementation?: Implementation, - options?: MockFunctionOptions, - ): Mock<(() => MockedObject[MethodName]) | Implementation>; - /** - * This function is syntax sugar for `MockTracker.method` with `options.setter` set to `true`. - * @since v19.3.0, v18.13.0 - */ - setter< - MockedObject extends object, - MethodName extends keyof MockedObject, - >( - object: MockedObject, - methodName: MethodName, - options?: MockFunctionOptions, - ): Mock<(value: MockedObject[MethodName]) => void>; - setter< - MockedObject extends object, - MethodName extends keyof MockedObject, - Implementation extends Function, - >( - object: MockedObject, - methodName: MethodName, - implementation?: Implementation, - options?: MockFunctionOptions, - ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>; - - /** - * This function is used to mock the exports of ECMAScript modules, CommonJS modules, and Node.js builtin modules. - * Any references to the original module prior to mocking are not impacted. - * - * Only available through the [--experimental-test-module-mocks](https://nodejs.org/api/cli.html#--experimental-test-module-mocks) flag. - * @since v22.3.0 - * @experimental - * @param specifier A string identifying the module to mock. - * @param options Optional configuration options for the mock module. - */ - module(specifier: string, options?: MockModuleOptions): MockModuleContext; - - /** - * 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 - * used to reset their behavior or - * otherwise interact with them. - * - * After each test completes, this function is called on the test context's `MockTracker`. If the global `MockTracker` is used extensively, calling this - * function manually is recommended. - * @since v19.1.0, v18.13.0 - */ - reset(): void; - /** - * This function restores the default behavior of all mocks that were previously - * created by this `MockTracker`. Unlike `mock.reset()`, `mock.restoreAll()` does - * not disassociate the mocks from the `MockTracker` instance. - * @since v19.1.0, v18.13.0 - */ - restoreAll(): void; - - timers: MockTimers; - } - const mock: MockTracker; - interface MockFunctionCall< - F extends Function, - ReturnType = F extends (...args: any) => infer T ? T - : F extends abstract new(...args: any) => infer T ? T - : unknown, - Args = F extends (...args: infer Y) => any ? Y - : F extends abstract new(...args: infer Y) => any ? Y - : unknown[], - > { - /** - * An array of the arguments passed to the mock function. - */ - arguments: Args; - /** - * If the mocked function threw then this property contains the thrown value. - */ - error: unknown | undefined; - /** - * The value returned by the mocked function. - * - * If the mocked function threw, it will be `undefined`. - */ - result: ReturnType | undefined; - /** - * An `Error` object whose stack can be used to determine the callsite of the mocked function invocation. - */ - stack: Error; - /** - * If the mocked function is a constructor, this field contains the class being constructed. - * Otherwise this will be `undefined`. - */ - target: F extends abstract new(...args: any) => any ? F : undefined; - /** - * The mocked function's `this` value. - */ - this: unknown; - } - /** - * The `MockFunctionContext` class is used to inspect or manipulate the behavior of - * mocks created via the `MockTracker` APIs. - * @since v19.1.0, v18.13.0 - */ - class MockFunctionContext { - /** - * A getter that returns a copy of the internal array used to track calls to the - * mock. Each entry in the array is an object with the following properties. - * @since v19.1.0, v18.13.0 - */ - readonly calls: Array>; - /** - * This function returns the number of times that this mock has been invoked. This - * function is more efficient than checking `ctx.calls.length` because `ctx.calls` is a getter that creates a copy of the internal call tracking array. - * @since v19.1.0, v18.13.0 - * @return The number of times that this mock has been invoked. - */ - callCount(): number; - /** - * This function is used to change the behavior of an existing mock. - * - * The following example creates a mock function using `t.mock.fn()`, calls the - * mock function, and then changes the mock implementation to a different function. - * - * ```js - * test('changes a mock behavior', (t) => { - * let cnt = 0; - * - * function addOne() { - * cnt++; - * return cnt; - * } - * - * function addTwo() { - * cnt += 2; - * return cnt; - * } - * - * const fn = t.mock.fn(addOne); - * - * assert.strictEqual(fn(), 1); - * fn.mock.mockImplementation(addTwo); - * assert.strictEqual(fn(), 3); - * assert.strictEqual(fn(), 5); - * }); - * ``` - * @since v19.1.0, v18.13.0 - * @param implementation The function to be used as the mock's new implementation. - */ - mockImplementation(implementation: F): void; - /** - * This function is used to change the behavior of an existing mock for a single - * invocation. Once invocation `onCall` 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.fn()`, calls the - * mock function, changes the mock implementation to a different function for the - * next invocation, and then resumes its previous behavior. - * - * ```js - * test('changes a mock behavior once', (t) => { - * let cnt = 0; - * - * function addOne() { - * cnt++; - * return cnt; - * } - * - * function addTwo() { - * cnt += 2; - * return cnt; - * } - * - * const fn = t.mock.fn(addOne); - * - * assert.strictEqual(fn(), 1); - * fn.mock.mockImplementationOnce(addTwo); - * assert.strictEqual(fn(), 3); - * assert.strictEqual(fn(), 4); - * }); - * ``` - * @since v19.1.0, v18.13.0 - * @param implementation The function to be used as the mock's implementation for the invocation number specified by `onCall`. - * @param onCall The invocation number that will use `implementation`. If the specified invocation has already occurred then an exception is thrown. - */ - mockImplementationOnce(implementation: F, onCall?: number): void; - /** - * Resets the call history of the mock function. - * @since v19.3.0, v18.13.0 - */ - resetCalls(): void; - /** - * Resets the implementation of the mock function to its original behavior. The - * mock can still be used after calling this function. - * @since v19.1.0, v18.13.0 - */ - restore(): void; - } - /** - * @since v22.3.0 - * @experimental - */ - class MockModuleContext { - /** - * Resets the implementation of the mock module. - * @since v22.3.0 - */ - restore(): void; - } - - type Timer = "setInterval" | "setTimeout" | "setImmediate" | "Date"; - interface MockTimersOptions { - apis: Timer[]; - now?: number | Date | undefined; - } - /** - * Mocking timers is a technique commonly used in software testing to simulate and - * control the behavior of timers, such as `setInterval` and `setTimeout`, - * without actually waiting for the specified time intervals. - * - * The MockTimers API also allows for mocking of the `Date` constructor and - * `setImmediate`/`clearImmediate` functions. - * - * The `MockTracker` provides a top-level `timers` export - * which is a `MockTimers` instance. - * @since v20.4.0 - * @experimental - */ - class MockTimers { - /** - * Enables timer mocking for the specified timers. - * - * **Note:** When you enable mocking for a specific timer, its associated - * clear function will also be implicitly mocked. - * - * **Note:** Mocking `Date` will affect the behavior of the mocked timers - * as they use the same internal clock. - * - * Example usage without setting initial time: - * - * ```js - * import { mock } from 'node:test'; - * mock.timers.enable({ apis: ['setInterval', 'Date'], now: 1234 }); - * ``` - * - * The above example enables mocking for the `Date` constructor, `setInterval` timer and - * implicitly mocks the `clearInterval` function. Only the `Date` constructor from `globalThis`, - * `setInterval` and `clearInterval` functions from `node:timers`, `node:timers/promises`, and `globalThis` will be mocked. - * - * Example usage with initial time set - * - * ```js - * import { mock } from 'node:test'; - * mock.timers.enable({ apis: ['Date'], now: 1000 }); - * ``` - * - * Example usage with initial Date object as time set - * - * ```js - * import { mock } from 'node:test'; - * mock.timers.enable({ apis: ['Date'], now: new Date() }); - * ``` - * - * Alternatively, if you call `mock.timers.enable()` without any parameters: - * - * All timers (`'setInterval'`, `'clearInterval'`, `'Date'`, `'setImmediate'`, `'clearImmediate'`, `'setTimeout'`, and `'clearTimeout'`) - * will be mocked. - * - * The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout` functions from `node:timers`, `node:timers/promises`, - * and `globalThis` will be mocked. - * The `Date` constructor from `globalThis` will be mocked. - * - * If there is no initial epoch set, the initial date will be based on 0 in the Unix epoch. This is `January 1st, 1970, 00:00:00 UTC`. You can - * set an initial date by passing a now property to the `.enable()` method. This value will be used as the initial date for the mocked Date - * object. It can either be a positive integer, or another Date object. - * @since v20.4.0 - */ - enable(options?: MockTimersOptions): void; + interface TestContext { + /** + * An object containing assertion methods bound to the test context. + * The top-level functions from the `node:assert` module are exposed here for the purpose of creating test plans. + * + * **Note:** Some of the functions from `node:assert` contain type assertions. If these are called via the + * TestContext `assert` object, then the context parameter in the test's function signature **must be explicitly typed** + * (ie. the parameter must have a type annotation), otherwise an error will be raised by the TypeScript compiler: + * ```ts + * import { test, type TestContext } from 'node:test'; + * + * // The test function's context parameter must have a type annotation. + * test('example', (t: TestContext) => { + * t.assert.deepStrictEqual(actual, expected); + * }); + * + * // Omitting the type annotation will result in a compilation error. + * test('example', t => { + * t.assert.deepStrictEqual(actual, expected); // Error: 't' needs an explicit type annotation. + * }); + * ``` + * @since v22.2.0, v20.15.0 + */ + readonly assert: TestContextAssert; + /** + * This function is used to create a hook running before subtest of the current test. + * @param fn The hook function. The first argument to this function is a `TestContext` object. + * If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. + * @since v20.1.0, v18.17.0 + */ + before(fn?: TestContextHookFn, options?: HookOptions): void; + /** + * This function is used to create a hook running before each subtest of the current test. + * @param fn The hook function. The first argument to this function is a `TestContext` object. + * If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. + * @since v18.8.0 + */ + beforeEach(fn?: TestContextHookFn, options?: HookOptions): void; + /** + * This function is used to create a hook that runs after the current test finishes. + * @param fn The hook function. The first argument to this function is a `TestContext` object. + * If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. + * @since v18.13.0 + */ + after(fn?: TestContextHookFn, options?: HookOptions): void; + /** + * This function is used to create a hook running after each subtest of the current test. + * @param fn The hook function. The first argument to this function is a `TestContext` object. + * If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. + * @since v18.8.0 + */ + afterEach(fn?: TestContextHookFn, options?: HookOptions): void; + /** + * This function is used to write diagnostics to the output. Any diagnostic + * information is included at the end of the test's results. This function does + * not return a value. + * + * ```js + * test('top level test', (t) => { + * t.diagnostic('A diagnostic message'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Message to be reported. + */ + diagnostic(message: string): void; + /** + * The absolute path of the test file that created the current test. If a test file imports + * additional modules that generate tests, the imported tests will return the path of the root test file. + * @since v22.6.0 + */ + readonly filePath: string | undefined; + /** + * The name of the test and each of its ancestors, separated by `>`. + * @since v22.3.0 + */ + readonly fullName: string; + /** + * The name of the test. + * @since v18.8.0, v16.18.0 + */ + readonly name: string; + /** + * This function is used to set the number of assertions and subtests that are expected to run + * within the test. If the number of assertions and subtests that run does not match the + * expected count, the test will fail. + * + * > Note: To make sure assertions are tracked, `t.assert` must be used instead of `assert` directly. + * + * ```js + * test('top level test', (t) => { + * t.plan(2); + * t.assert.ok('some relevant assertion here'); + * t.test('subtest', () => {}); + * }); + * ``` + * + * When working with asynchronous code, the `plan` function can be used to ensure that the + * correct number of assertions are run: + * + * ```js + * test('planning with streams', (t, done) => { + * function* generate() { + * yield 'a'; + * yield 'b'; + * yield 'c'; + * } + * const expected = ['a', 'b', 'c']; + * t.plan(expected.length); + * const stream = Readable.from(generate()); + * stream.on('data', (chunk) => { + * t.assert.strictEqual(chunk, expected.shift()); + * }); + * + * stream.on('end', () => { + * done(); + * }); + * }); + * ``` + * + * When using the `wait` option, you can control how long the test will wait for the expected assertions. + * For example, setting a maximum wait time ensures that the test will wait for asynchronous assertions + * to complete within the specified timeframe: + * + * ```js + * test('plan with wait: 2000 waits for async assertions', (t) => { + * t.plan(1, { wait: 2000 }); // Waits for up to 2 seconds for the assertion to complete. + * + * const asyncActivity = () => { + * setTimeout(() => { + * * t.assert.ok(true, 'Async assertion completed within the wait time'); + * }, 1000); // Completes after 1 second, within the 2-second wait time. + * }; + * + * asyncActivity(); // The test will pass because the assertion is completed in time. + * }); + * ``` + * + * Note: If a `wait` timeout is specified, it begins counting down only after the test function finishes executing. + * @since v22.2.0 + */ + plan(count: number, options?: TestContextPlanOptions): void; + /** + * If `shouldRunOnlyTests` is truthy, the test context will only run tests that + * have the `only` option set. Otherwise, all tests are run. If Node.js was not + * started with the `--test-only` command-line option, this function is a + * no-op. + * + * ```js + * test('top level test', (t) => { + * // The test context can be set to run subtests with the 'only' option. + * t.runOnly(true); + * return Promise.all([ + * t.test('this subtest is now skipped'), + * t.test('this subtest is run', { only: true }), + * ]); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param shouldRunOnlyTests Whether or not to run `only` tests. + */ + runOnly(shouldRunOnlyTests: boolean): void; + /** + * ```js + * test('top level test', async (t) => { + * await fetch('some/uri', { signal: t.signal }); + * }); + * ``` + * @since v18.7.0, v16.17.0 + */ + readonly signal: AbortSignal; + /** + * This function causes the test's output to indicate the test as skipped. If `message` is provided, it is included in the output. Calling `skip()` does + * not terminate execution of the test function. This function does not return a + * value. + * + * ```js + * test('top level test', (t) => { + * // Make sure to return here as well if the test contains additional logic. + * t.skip('this is skipped'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Optional skip message. + */ + skip(message?: string): void; + /** + * This function adds a `TODO` directive to the test's output. If `message` is + * provided, it is included in the output. Calling `todo()` does not terminate + * execution of the test function. This function does not return a value. + * + * ```js + * test('top level test', (t) => { + * // This test is marked as `TODO` + * t.todo('this is a todo'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Optional `TODO` message. + */ + todo(message?: string): void; + /** + * This function is used to create subtests under the current test. This function behaves in + * the same fashion as the top level {@link test} function. + * @since v18.0.0 + * @param name The name of the test, which is displayed when reporting test results. + * Defaults to the `name` property of `fn`, or `''` if `fn` does not have a name. + * @param options Configuration options for the test. + * @param fn The function under test. This first argument to this function is a {@link TestContext} object. + * If the test uses callbacks, the callback function is passed as the second argument. + * @returns A {@link Promise} resolved with `undefined` once the test completes. + */ + test: typeof test; + /** + * This method polls a `condition` function until that function either returns + * successfully or the operation times out. + * @since v22.14.0 + * @param condition An assertion function that is invoked + * periodically until it completes successfully or the defined polling timeout + * elapses. Successful completion is defined as not throwing or rejecting. This + * function does not accept any arguments, and is allowed to return any value. + * @param options An optional configuration object for the polling operation. + * @returns Fulfilled with the value returned by `condition`. + */ + waitFor(condition: () => T, options?: TestContextWaitForOptions): Promise>; + /** + * Each test provides its own MockTracker instance. + */ + readonly mock: MockTracker; + } + interface TestContextAssert extends + Pick< + typeof import("assert"), + | "deepEqual" + | "deepStrictEqual" + | "doesNotMatch" + | "doesNotReject" + | "doesNotThrow" + | "equal" + | "fail" + | "ifError" + | "match" + | "notDeepEqual" + | "notDeepStrictEqual" + | "notEqual" + | "notStrictEqual" + | "ok" + | "partialDeepStrictEqual" + | "rejects" + | "strictEqual" + | "throws" + > + { + /** + * This function serializes `value` and writes it to the file specified by `path`. + * + * ```js + * test('snapshot test with default serialization', (t) => { + * t.assert.fileSnapshot({ value1: 1, value2: 2 }, './snapshots/snapshot.json'); + * }); + * ``` + * + * This function differs from `context.assert.snapshot()` in the following ways: + * + * * The snapshot file path is explicitly provided by the user. + * * Each snapshot file is limited to a single snapshot value. + * * No additional escaping is performed by the test runner. + * + * These differences allow snapshot files to better support features such as syntax + * highlighting. + * @since v22.14.0 + * @param value A value to serialize to a string. If Node.js was started with + * the [`--test-update-snapshots`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--test-update-snapshots) + * flag, the serialized value is written to + * `path`. Otherwise, the serialized value is compared to the contents of the + * existing snapshot file. + * @param path The file where the serialized `value` is written. + * @param options Optional configuration options. + */ + fileSnapshot(value: any, path: string, options?: AssertSnapshotOptions): void; + /** + * This function implements assertions for snapshot testing. + * ```js + * test('snapshot test with default serialization', (t) => { + * t.assert.snapshot({ value1: 1, value2: 2 }); + * }); + * + * test('snapshot test with custom serialization', (t) => { + * t.assert.snapshot({ value3: 3, value4: 4 }, { + * serializers: [(value) => JSON.stringify(value)] + * }); + * }); + * ``` + * @since v22.3.0 + * @param value A value to serialize to a string. If Node.js was started with + * the [`--test-update-snapshots`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--test-update-snapshots) + * flag, the serialized value is written to + * the snapshot file. Otherwise, the serialized value is compared to the + * corresponding value in the existing snapshot file. + */ + snapshot(value: any, options?: AssertSnapshotOptions): void; + /** + * A custom assertion function registered with `assert.register()`. + */ + [name: string]: (...args: any[]) => void; + } + interface AssertSnapshotOptions { + /** + * An array of synchronous functions used to serialize `value` into a string. + * `value` is passed as the only argument to the first serializer function. + * The return value of each serializer is passed as input to the next serializer. + * Once all serializers have run, the resulting value is coerced to a string. + * + * If no serializers are provided, the test runner's default serializers are used. + */ + serializers?: ReadonlyArray<(value: any) => any> | undefined; + } + interface TestContextPlanOptions { + /** + * The wait time for the plan: + * * If `true`, the plan waits indefinitely for all assertions and subtests to run. + * * If `false`, the plan performs an immediate check after the test function completes, + * without waiting for any pending assertions or subtests. + * Any assertions or subtests that complete after this check will not be counted towards the plan. + * * If a number, it specifies the maximum wait time in milliseconds + * before timing out while waiting for expected assertions and subtests to be matched. + * If the timeout is reached, the test will fail. + * @default false + */ + wait?: boolean | number | undefined; + } + interface TestContextWaitForOptions { + /** + * The number of milliseconds to wait after an unsuccessful + * invocation of `condition` before trying again. + * @default 50 + */ + interval?: number | undefined; + /** + * The poll timeout in milliseconds. If `condition` has not + * succeeded by the time this elapses, an error occurs. + * @default 1000 + */ + timeout?: number | undefined; + } /** - * You can use the `.setTime()` method to manually move the mocked date to another time. This method only accepts a positive integer. - * Note: This method will execute any mocked timers that are in the past from the new time. - * In the below example we are setting a new time for the mocked date. - * ```js - * import assert from 'node:assert'; - * import { test } from 'node:test'; - * test('sets the time of a date object', (context) => { - * // Optionally choose what to mock - * context.mock.timers.enable({ apis: ['Date'], now: 100 }); - * assert.strictEqual(Date.now(), 100); - * // Advance in time will also advance the date - * context.mock.timers.setTime(1000); - * context.mock.timers.tick(200); - * assert.strictEqual(Date.now(), 1200); - * }); - * ``` + * An instance of `SuiteContext` is passed to each suite function in order to + * interact with the test runner. However, the `SuiteContext` constructor is not + * exposed as part of the API. + * @since v18.7.0, v16.17.0 */ - setTime(time: number): void; + interface SuiteContext { + /** + * The absolute path of the test file that created the current suite. If a test file imports + * additional modules that generate suites, the imported suites will return the path of the root test file. + * @since v22.6.0 + */ + readonly filePath: string | undefined; + /** + * The name of the suite. + * @since v18.8.0, v16.18.0 + */ + readonly name: string; + /** + * Can be used to abort test subtasks when the test has been aborted. + * @since v18.7.0, v16.17.0 + */ + readonly signal: AbortSignal; + } + interface TestOptions { + /** + * If a number is provided, then that many tests would run in parallel. + * If truthy, it would run (number of cpu cores - 1) tests in parallel. + * For subtests, it will be `Infinity` tests in parallel. + * If falsy, it would only run one test at a time. + * If unspecified, subtests inherit this value from their parent. + * @default false + */ + concurrency?: number | boolean | undefined; + /** + * If truthy, and the test context is configured to run `only` tests, then this test will be + * run. Otherwise, the test is skipped. + * @default false + */ + only?: boolean | undefined; + /** + * Allows aborting an in-progress test. + * @since v18.8.0 + */ + signal?: AbortSignal | undefined; + /** + * If truthy, the test is skipped. If a string is provided, that string is displayed in the + * test results as the reason for skipping the test. + * @default false + */ + skip?: boolean | string | undefined; + /** + * A number of milliseconds the test will fail after. If unspecified, subtests inherit this + * value from their parent. + * @default Infinity + * @since v18.7.0 + */ + timeout?: number | undefined; + /** + * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in + * the test results as the reason why the test is `TODO`. + * @default false + */ + todo?: boolean | string | undefined; + /** + * The number of assertions and subtests expected to be run in the test. + * If the number of assertions run in the test does not match the number + * specified in the plan, the test will fail. + * @default undefined + * @since v22.2.0 + */ + plan?: number | undefined; + } /** - * This function restores the default behavior of all mocks that were previously - * created by this `MockTimers` instance and disassociates the mocks - * from the `MockTracker` instance. - * - * **Note:** After each test completes, this function is called on - * the test context's `MockTracker`. + * This function creates a hook that runs before executing a suite. * * ```js - * import { mock } from 'node:test'; - * mock.timers.reset(); + * describe('tests', async () => { + * before(() => console.log('about to run some test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); * ``` - * @since v20.4.0 + * @since v18.8.0, v16.18.0 + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. */ - reset(): void; + function before(fn?: HookFn, options?: HookOptions): void; /** - * Advances time for all mocked timers. - * - * **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts - * only positive numbers. In Node.js, `setTimeout` with negative numbers is - * only supported for web compatibility reasons. - * - * The following example mocks a `setTimeout` function and - * by using `.tick` advances in - * time triggering all pending timers. - * - * ```js - * import assert from 'node:assert'; - * import { test } from 'node:test'; - * - * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { - * const fn = context.mock.fn(); - * - * context.mock.timers.enable({ apis: ['setTimeout'] }); - * - * setTimeout(fn, 9999); - * - * assert.strictEqual(fn.mock.callCount(), 0); - * - * // Advance in time - * context.mock.timers.tick(9999); - * - * assert.strictEqual(fn.mock.callCount(), 1); - * }); - * ``` - * - * Alternativelly, the `.tick` function can be called many times + * This function creates a hook that runs after executing a suite. * * ```js - * import assert from 'node:assert'; - * import { test } from 'node:test'; - * - * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { - * const fn = context.mock.fn(); - * context.mock.timers.enable({ apis: ['setTimeout'] }); - * const nineSecs = 9000; - * setTimeout(fn, nineSecs); - * - * const twoSeconds = 3000; - * context.mock.timers.tick(twoSeconds); - * context.mock.timers.tick(twoSeconds); - * context.mock.timers.tick(twoSeconds); - * - * assert.strictEqual(fn.mock.callCount(), 1); + * describe('tests', async () => { + * after(() => console.log('finished running tests')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); * }); * ``` - * - * Advancing time using `.tick` will also advance the time for any `Date` object - * created after the mock was enabled (if `Date` was also set to be mocked). + * @since v18.8.0, v16.18.0 + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. + */ + function after(fn?: HookFn, options?: HookOptions): void; + /** + * This function creates a hook that runs before each test in the current suite. * * ```js - * import assert from 'node:assert'; - * import { test } from 'node:test'; - * - * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { - * const fn = context.mock.fn(); - * - * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] }); - * setTimeout(fn, 9999); - * - * assert.strictEqual(fn.mock.callCount(), 0); - * assert.strictEqual(Date.now(), 0); - * - * // Advance in time - * context.mock.timers.tick(9999); - * assert.strictEqual(fn.mock.callCount(), 1); - * assert.strictEqual(Date.now(), 9999); + * describe('tests', async () => { + * beforeEach(() => console.log('about to run a test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); * }); * ``` - * @since v20.4.0 + * @since v18.8.0, v16.18.0 + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. */ - tick(milliseconds: number): void; + function beforeEach(fn?: HookFn, options?: HookOptions): void; /** - * Triggers all pending mocked timers immediately. If the `Date` object is also - * mocked, it will also advance the `Date` object to the furthest timer's time. - * - * The example below triggers all pending timers immediately, - * causing them to execute without any delay. + * This function creates a hook that runs after each test in the current suite. + * The `afterEach()` hook is run even if the test fails. * * ```js - * import assert from 'node:assert'; - * import { test } from 'node:test'; - * - * test('runAll functions following the given order', (context) => { - * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] }); - * const results = []; - * setTimeout(() => results.push(1), 9999); - * - * // Notice that if both timers have the same timeout, - * // the order of execution is guaranteed - * setTimeout(() => results.push(3), 8888); - * setTimeout(() => results.push(2), 8888); - * - * assert.deepStrictEqual(results, []); - * - * context.mock.timers.runAll(); - * assert.deepStrictEqual(results, [3, 2, 1]); - * // The Date object is also advanced to the furthest timer's time - * assert.strictEqual(Date.now(), 9999); + * describe('tests', async () => { + * afterEach(() => console.log('finished running a test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); * }); * ``` - * - * **Note:** The `runAll()` function is specifically designed for - * triggering timers in the context of timer mocking. - * It does not have any effect on real-time system - * clocks or actual timers outside of the mocking environment. - * @since v20.4.0 + * @since v18.8.0, v16.18.0 + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. */ - runAll(): void; + function afterEach(fn?: HookFn, options?: HookOptions): void; /** - * Calls {@link MockTimers.reset()}. + * The hook function. The first argument is the context in which the hook is called. + * If the hook uses callbacks, the callback function is passed as the second argument. */ - [Symbol.dispose](): void; - } - /** - * Only available through the [--experimental-test-snapshots](https://nodejs.org/api/cli.html#--experimental-test-snapshots) flag. - * @since v22.3.0 - * @experimental - */ - namespace snapshot { + type HookFn = (c: TestContext | SuiteContext, done: (result?: any) => void) => any; /** - * This function is used to customize the default serialization mechanism used by the test runner. - * - * By default, the test runner performs serialization by calling `JSON.stringify(value, null, 2)` on the provided value. - * `JSON.stringify()` does have limitations regarding circular structures and supported data types. - * If a more robust serialization mechanism is required, this function should be used to specify a list of custom serializers. - * - * Serializers are called in order, with the output of the previous serializer passed as input to the next. - * The final result must be a string value. - * @since v22.3.0 - * @param serializers An array of synchronous functions used as the default serializers for snapshot tests. + * The hook function. The first argument is a `TestContext` object. + * If the hook uses callbacks, the callback function is passed as the second argument. */ - function setDefaultSnapshotSerializers(serializers: ReadonlyArray<(value: any) => any>): void; + type TestContextHookFn = (t: TestContext, done: (result?: any) => void) => any; /** - * This function is used to set a custom resolver for the location of the snapshot file used for snapshot testing. - * By default, the snapshot filename is the same as the entry point filename with `.snapshot` appended. - * @since v22.3.0 - * @param fn A function which returns a string specifying the location of the snapshot file. - * The function receives the path of the test file as its only argument. - * If `process.argv[1]` is not associated with a file (for example in the REPL), the input is undefined. + * Configuration options for hooks. + * @since v18.8.0 */ - function setResolveSnapshotPath(fn: (path: string | undefined) => string): void; - } - export { - after, - afterEach, - before, - beforeEach, - describe, - it, - Mock, - mock, - only, - run, - skip, - snapshot, - suite, - SuiteContext, - test, - test as default, - TestContext, - todo, - }; -} - -interface TestError extends Error { - cause: Error; -} -interface TestLocationInfo { - /** - * The column number where the test is defined, or - * `undefined` if the test was run through the REPL. - */ - column?: number; - /** - * The path of the test file, `undefined` if test was run through the REPL. - */ - file?: string; - /** - * The line number where the test is defined, or `undefined` if the test was run through the REPL. - */ - line?: number; -} -interface DiagnosticData extends TestLocationInfo { - /** - * The diagnostic message. - */ - message: string; - /** - * The nesting level of the test. - */ - nesting: number; -} -interface TestCoverage { - /** - * An object containing the coverage report. - */ - summary: { + interface HookOptions { + /** + * Allows aborting an in-progress hook. + */ + signal?: AbortSignal | undefined; + /** + * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this + * value from their parent. + * @default Infinity + */ + timeout?: number | undefined; + } + interface MockFunctionOptions { + /** + * The number of times that the mock will use the behavior of `implementation`. + * Once the mock function has been called `times` times, + * it will automatically restore the behavior of `original`. + * This value must be an integer greater than zero. + * @default Infinity + */ + times?: number | undefined; + } + interface MockMethodOptions extends MockFunctionOptions { + /** + * If `true`, `object[methodName]` is treated as a getter. + * This option cannot be used with the `setter` option. + */ + getter?: boolean | undefined; + /** + * If `true`, `object[methodName]` is treated as a setter. + * This option cannot be used with the `getter` option. + */ + setter?: boolean | undefined; + } + type Mock = F & { + mock: MockFunctionContext; + }; + interface MockModuleOptions { + /** + * If false, each call to `require()` or `import()` generates a new mock module. + * If true, subsequent calls will return the same module mock, and the mock module is inserted into the CommonJS cache. + * @default false + */ + cache?: boolean | undefined; + /** + * The value to use as the mocked module's default export. + * + * If this value is not provided, ESM mocks do not include a default export. + * If the mock is a CommonJS or builtin module, this setting is used as the value of `module.exports`. + * If this value is not provided, CJS and builtin mocks use an empty object as the value of `module.exports`. + */ + defaultExport?: any; + /** + * An object whose keys and values are used to create the named exports of the mock module. + * + * If the mock is a CommonJS or builtin module, these values are copied onto `module.exports`. + * Therefore, if a mock is created with both named exports and a non-object default export, + * the mock will throw an exception when used as a CJS or builtin module. + */ + namedExports?: object | undefined; + } /** - * An array of coverage reports for individual files. + * The `MockTracker` class is used to manage mocking functionality. The test runner + * module provides a top level `mock` export which is a `MockTracker` instance. + * Each test also provides its own `MockTracker` instance via the test context's `mock` property. + * @since v19.1.0, v18.13.0 */ - files: Array<{ + interface MockTracker { /** - * The absolute path of the file. + * This function is used to create a mock function. + * + * The following example creates a mock function that increments a counter by one + * on each invocation. The `times` option is used to modify the mock behavior such + * that the first two invocations add two to the counter instead of one. + * + * ```js + * test('mocks a counting function', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne, addTwo, { times: 2 }); + * + * assert.strictEqual(fn(), 2); + * assert.strictEqual(fn(), 4); + * assert.strictEqual(fn(), 5); + * assert.strictEqual(fn(), 6); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param original An optional function to create a mock on. + * @param implementation An optional function used as the mock implementation for `original`. This is useful for creating mocks that exhibit one behavior for a specified number of calls and + * then restore the behavior of `original`. + * @param options Optional configuration options for the mock function. + * @return The mocked function. The mocked function contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the + * behavior of the mocked function. */ - path: string; + fn undefined>( + original?: F, + options?: MockFunctionOptions, + ): Mock; + fn undefined, Implementation extends Function = F>( + original?: F, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock; /** - * The total number of lines. + * This function is used to create a mock on an existing object method. The + * following example demonstrates how a mock is created on an existing object + * method. + * + * ```js + * test('spies on an object method', (t) => { + * const number = { + * value: 5, + * subtract(a) { + * return this.value - a; + * }, + * }; + * + * t.mock.method(number, 'subtract'); + * assert.strictEqual(number.subtract.mock.calls.length, 0); + * assert.strictEqual(number.subtract(3), 2); + * assert.strictEqual(number.subtract.mock.calls.length, 1); + * + * const call = number.subtract.mock.calls[0]; + * + * assert.deepStrictEqual(call.arguments, [3]); + * assert.strictEqual(call.result, 2); + * assert.strictEqual(call.error, undefined); + * assert.strictEqual(call.target, undefined); + * assert.strictEqual(call.this, number); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param object The object whose method is being mocked. + * @param methodName The identifier of the method on `object` to mock. If `object[methodName]` is not a function, an error is thrown. + * @param implementation An optional function used as the mock implementation for `object[methodName]`. + * @param options Optional configuration options for the mock method. + * @return The mocked method. The mocked method contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the + * behavior of the mocked method. */ - totalLineCount: number; + method< + MockedObject extends object, + MethodName extends FunctionPropertyNames, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): MockedObject[MethodName] extends Function ? Mock + : never; + method< + MockedObject extends object, + MethodName extends FunctionPropertyNames, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation: Implementation, + options?: MockFunctionOptions, + ): MockedObject[MethodName] extends Function ? Mock + : never; + method( + object: MockedObject, + methodName: keyof MockedObject, + options: MockMethodOptions, + ): Mock; + method( + object: MockedObject, + methodName: keyof MockedObject, + implementation: Function, + options: MockMethodOptions, + ): Mock; /** - * The total number of branches. + * This function is syntax sugar for `MockTracker.method` with `options.getter` set to `true`. + * @since v19.3.0, v18.13.0 */ - totalBranchCount: number; + getter< + MockedObject extends object, + MethodName extends keyof MockedObject, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): Mock<() => MockedObject[MethodName]>; + getter< + MockedObject extends object, + MethodName extends keyof MockedObject, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock<(() => MockedObject[MethodName]) | Implementation>; /** - * The total number of functions. + * This function is syntax sugar for `MockTracker.method` with `options.setter` set to `true`. + * @since v19.3.0, v18.13.0 */ - totalFunctionCount: number; + setter< + MockedObject extends object, + MethodName extends keyof MockedObject, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): Mock<(value: MockedObject[MethodName]) => void>; + setter< + MockedObject extends object, + MethodName extends keyof MockedObject, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>; /** - * The number of covered lines. + * This function is used to mock the exports of ECMAScript modules, CommonJS modules, and Node.js builtin modules. + * Any references to the original module prior to mocking are not impacted. + * + * Only available through the [--experimental-test-module-mocks](https://nodejs.org/api/cli.html#--experimental-test-module-mocks) flag. + * @since v22.3.0 + * @experimental + * @param specifier A string identifying the module to mock. + * @param options Optional configuration options for the mock module. */ - coveredLineCount: number; + module(specifier: string, options?: MockModuleOptions): MockModuleContext; /** - * The number of covered branches. + * 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 + * used to reset their behavior or + * otherwise interact with them. + * + * After each test completes, this function is called on the test context's `MockTracker`. If the global `MockTracker` is used extensively, calling this + * function manually is recommended. + * @since v19.1.0, v18.13.0 */ - coveredBranchCount: number; + reset(): void; /** - * The number of covered functions. + * This function restores the default behavior of all mocks that were previously + * created by this `MockTracker`. Unlike `mock.reset()`, `mock.restoreAll()` does + * not disassociate the mocks from the `MockTracker` instance. + * @since v19.1.0, v18.13.0 */ - coveredFunctionCount: number; + restoreAll(): void; + readonly timers: MockTimers; + } + const mock: MockTracker; + interface MockFunctionCall< + F extends Function, + ReturnType = F extends (...args: any) => infer T ? T + : F extends abstract new(...args: any) => infer T ? T + : unknown, + Args = F extends (...args: infer Y) => any ? Y + : F extends abstract new(...args: infer Y) => any ? Y + : unknown[], + > { /** - * The percentage of lines covered. + * An array of the arguments passed to the mock function. */ - coveredLinePercent: number; + arguments: Args; /** - * The percentage of branches covered. + * If the mocked function threw then this property contains the thrown value. */ - coveredBranchPercent: number; + error: unknown | undefined; /** - * The percentage of functions covered. + * The value returned by the mocked function. + * + * If the mocked function threw, it will be `undefined`. */ - coveredFunctionPercent: number; + result: ReturnType | undefined; /** - * An array of functions representing function coverage. + * An `Error` object whose stack can be used to determine the callsite of the mocked function invocation. */ - functions: Array<{ - /** - * The name of the function. - */ - name: string; - /** - * The line number where the function is defined. - */ - line: number; - /** - * The number of times the function was called. - */ - count: number; - }>; + stack: Error; /** - * An array of branches representing branch coverage. + * If the mocked function is a constructor, this field contains the class being constructed. + * Otherwise this will be `undefined`. */ - branches: Array<{ - /** - * The line number where the branch is defined. - */ - line: number; - /** - * The number of times the branch was taken. - */ - count: number; - }>; + target: F extends abstract new(...args: any) => any ? F : undefined; /** - * An array of lines representing line numbers and the number of times they were covered. + * The mocked function's `this` value. */ - lines: Array<{ - /** - * The line number. - */ - line: number; - /** - * The number of times the line was covered. - */ - count: number; - }>; - }>; + this: unknown; + } /** - * An object containing a summary of coverage for all files. + * The `MockFunctionContext` class is used to inspect or manipulate the behavior of + * mocks created via the `MockTracker` APIs. + * @since v19.1.0, v18.13.0 */ - totals: { + interface MockFunctionContext { /** - * The total number of lines. + * A getter that returns a copy of the internal array used to track calls to the + * mock. Each entry in the array is an object with the following properties. + * @since v19.1.0, v18.13.0 */ - totalLineCount: number; + readonly calls: MockFunctionCall[]; /** - * The total number of branches. + * This function returns the number of times that this mock has been invoked. This + * function is more efficient than checking `ctx.calls.length` because `ctx.calls` is a getter that creates a copy of the internal call tracking array. + * @since v19.1.0, v18.13.0 + * @return The number of times that this mock has been invoked. */ - totalBranchCount: number; + callCount(): number; /** - * The total number of functions. + * This function is used to change the behavior of an existing mock. + * + * The following example creates a mock function using `t.mock.fn()`, calls the + * mock function, and then changes the mock implementation to a different function. + * + * ```js + * test('changes a mock behavior', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne); + * + * assert.strictEqual(fn(), 1); + * fn.mock.mockImplementation(addTwo); + * assert.strictEqual(fn(), 3); + * assert.strictEqual(fn(), 5); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param implementation The function to be used as the mock's new implementation. */ - totalFunctionCount: number; + mockImplementation(implementation: F): void; /** - * The number of covered lines. + * This function is used to change the behavior of an existing mock for a single + * invocation. Once invocation `onCall` 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.fn()`, calls the + * mock function, changes the mock implementation to a different function for the + * next invocation, and then resumes its previous behavior. + * + * ```js + * test('changes a mock behavior once', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne); + * + * assert.strictEqual(fn(), 1); + * fn.mock.mockImplementationOnce(addTwo); + * assert.strictEqual(fn(), 3); + * assert.strictEqual(fn(), 4); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param implementation The function to be used as the mock's implementation for the invocation number specified by `onCall`. + * @param onCall The invocation number that will use `implementation`. If the specified invocation has already occurred then an exception is thrown. */ - coveredLineCount: number; + mockImplementationOnce(implementation: F, onCall?: number): void; /** - * The number of covered branches. + * Resets the call history of the mock function. + * @since v19.3.0, v18.13.0 */ - coveredBranchCount: number; + resetCalls(): void; /** - * The number of covered functions. + * Resets the implementation of the mock function to its original behavior. The + * mock can still be used after calling this function. + * @since v19.1.0, v18.13.0 */ - coveredFunctionCount: number; + restore(): void; + } + /** + * @since v22.3.0 + * @experimental + */ + interface MockModuleContext { /** - * The percentage of lines covered. + * Resets the implementation of the mock module. + * @since v22.3.0 */ - coveredLinePercent: number; + restore(): void; + } + interface MockTimersOptions { + apis: ReadonlyArray<"setInterval" | "setTimeout" | "setImmediate" | "Date">; + now?: number | Date | undefined; + } + /** + * Mocking timers is a technique commonly used in software testing to simulate and + * control the behavior of timers, such as `setInterval` and `setTimeout`, + * without actually waiting for the specified time intervals. + * + * The MockTimers API also allows for mocking of the `Date` constructor and + * `setImmediate`/`clearImmediate` functions. + * + * The `MockTracker` provides a top-level `timers` export + * which is a `MockTimers` instance. + * @since v20.4.0 + * @experimental + */ + interface MockTimers { /** - * The percentage of branches covered. + * Enables timer mocking for the specified timers. + * + * **Note:** When you enable mocking for a specific timer, its associated + * clear function will also be implicitly mocked. + * + * **Note:** Mocking `Date` will affect the behavior of the mocked timers + * as they use the same internal clock. + * + * Example usage without setting initial time: + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['setInterval', 'Date'], now: 1234 }); + * ``` + * + * The above example enables mocking for the `Date` constructor, `setInterval` timer and + * implicitly mocks the `clearInterval` function. Only the `Date` constructor from `globalThis`, + * `setInterval` and `clearInterval` functions from `node:timers`, `node:timers/promises`, and `globalThis` will be mocked. + * + * Example usage with initial time set + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['Date'], now: 1000 }); + * ``` + * + * Example usage with initial Date object as time set + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['Date'], now: new Date() }); + * ``` + * + * Alternatively, if you call `mock.timers.enable()` without any parameters: + * + * All timers (`'setInterval'`, `'clearInterval'`, `'Date'`, `'setImmediate'`, `'clearImmediate'`, `'setTimeout'`, and `'clearTimeout'`) + * will be mocked. + * + * The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout` functions from `node:timers`, `node:timers/promises`, + * and `globalThis` will be mocked. + * The `Date` constructor from `globalThis` will be mocked. + * + * If there is no initial epoch set, the initial date will be based on 0 in the Unix epoch. This is `January 1st, 1970, 00:00:00 UTC`. You can + * set an initial date by passing a now property to the `.enable()` method. This value will be used as the initial date for the mocked Date + * object. It can either be a positive integer, or another Date object. + * @since v20.4.0 */ - coveredBranchPercent: number; + enable(options?: MockTimersOptions): void; /** - * The percentage of functions covered. + * You can use the `.setTime()` method to manually move the mocked date to another time. This method only accepts a positive integer. + * Note: This method will execute any mocked timers that are in the past from the new time. + * In the below example we are setting a new time for the mocked date. + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * test('sets the time of a date object', (context) => { + * // Optionally choose what to mock + * context.mock.timers.enable({ apis: ['Date'], now: 100 }); + * assert.strictEqual(Date.now(), 100); + * // Advance in time will also advance the date + * context.mock.timers.setTime(1000); + * context.mock.timers.tick(200); + * assert.strictEqual(Date.now(), 1200); + * }); + * ``` */ - coveredFunctionPercent: number; - }; - /** - * The working directory when code coverage began. This - * is useful for displaying relative path names in case - * the tests changed the working directory of the Node.js process. - */ - workingDirectory: string; - }; - /** - * The nesting level of the test. - */ - nesting: number; -} -interface TestComplete extends TestLocationInfo { - /** - * Additional execution metadata. - */ - details: { - /** - * Whether the test passed or not. - */ - passed: boolean; - /** - * The duration of the test in milliseconds. - */ - duration_ms: number; - /** - * An error wrapping the error thrown by the test if it did not pass. - */ - error?: TestError; - /** - * The type of the test, used to denote whether this is a suite. - */ - type?: "suite"; - }; - /** - * The test name. - */ - name: string; - /** - * The nesting level of the test. - */ - nesting: number; - /** - * The ordinal number of the test. - */ - testNumber: number; - /** - * Present if `context.todo` is called. - */ - todo?: string | boolean; - /** - * Present if `context.skip` is called. - */ - skip?: string | boolean; -} -interface TestDequeue extends TestLocationInfo { - /** - * The test name. - */ - name: string; - /** - * The nesting level of the test. - */ - nesting: number; -} -interface TestEnqueue extends TestLocationInfo { - /** - * The test name. - */ - name: string; - /** - * The nesting level of the test. - */ - nesting: number; -} -interface TestFail extends TestLocationInfo { - /** - * Additional execution metadata. - */ - details: { - /** - * The duration of the test in milliseconds. - */ - duration_ms: number; - /** - * An error wrapping the error thrown by the test. - */ - error: TestError; - /** - * The type of the test, used to denote whether this is a suite. - * @since v20.0.0, v19.9.0, v18.17.0 - */ - type?: "suite"; - }; - /** - * The test name. - */ - name: string; - /** - * The nesting level of the test. - */ - nesting: number; - /** - * The ordinal number of the test. - */ - testNumber: number; - /** - * Present if `context.todo` is called. - */ - todo?: string | boolean; - /** - * Present if `context.skip` is called. - */ - skip?: string | boolean; -} -interface TestPass extends TestLocationInfo { - /** - * Additional execution metadata. - */ - details: { + setTime(time: number): void; + /** + * This function restores the default behavior of all mocks that were previously + * created by this `MockTimers` instance and disassociates the mocks + * from the `MockTracker` instance. + * + * **Note:** After each test completes, this function is called on + * the test context's `MockTracker`. + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.reset(); + * ``` + * @since v20.4.0 + */ + reset(): void; + /** + * Advances time for all mocked timers. + * + * **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts + * only positive numbers. In Node.js, `setTimeout` with negative numbers is + * only supported for web compatibility reasons. + * + * The following example mocks a `setTimeout` function and + * by using `.tick` advances in + * time triggering all pending timers. + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * + * context.mock.timers.enable({ apis: ['setTimeout'] }); + * + * setTimeout(fn, 9999); + * + * assert.strictEqual(fn.mock.callCount(), 0); + * + * // Advance in time + * context.mock.timers.tick(9999); + * + * assert.strictEqual(fn.mock.callCount(), 1); + * }); + * ``` + * + * Alternativelly, the `.tick` function can be called many times + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * context.mock.timers.enable({ apis: ['setTimeout'] }); + * const nineSecs = 9000; + * setTimeout(fn, nineSecs); + * + * const twoSeconds = 3000; + * context.mock.timers.tick(twoSeconds); + * context.mock.timers.tick(twoSeconds); + * context.mock.timers.tick(twoSeconds); + * + * assert.strictEqual(fn.mock.callCount(), 1); + * }); + * ``` + * + * Advancing time using `.tick` will also advance the time for any `Date` object + * created after the mock was enabled (if `Date` was also set to be mocked). + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * + * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] }); + * setTimeout(fn, 9999); + * + * assert.strictEqual(fn.mock.callCount(), 0); + * assert.strictEqual(Date.now(), 0); + * + * // Advance in time + * context.mock.timers.tick(9999); + * assert.strictEqual(fn.mock.callCount(), 1); + * assert.strictEqual(Date.now(), 9999); + * }); + * ``` + * @since v20.4.0 + */ + tick(milliseconds: number): void; + /** + * Triggers all pending mocked timers immediately. If the `Date` object is also + * mocked, it will also advance the `Date` object to the furthest timer's time. + * + * The example below triggers all pending timers immediately, + * causing them to execute without any delay. + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('runAll functions following the given order', (context) => { + * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] }); + * const results = []; + * setTimeout(() => results.push(1), 9999); + * + * // Notice that if both timers have the same timeout, + * // the order of execution is guaranteed + * setTimeout(() => results.push(3), 8888); + * setTimeout(() => results.push(2), 8888); + * + * assert.deepStrictEqual(results, []); + * + * context.mock.timers.runAll(); + * assert.deepStrictEqual(results, [3, 2, 1]); + * // The Date object is also advanced to the furthest timer's time + * assert.strictEqual(Date.now(), 9999); + * }); + * ``` + * + * **Note:** The `runAll()` function is specifically designed for + * triggering timers in the context of timer mocking. + * It does not have any effect on real-time system + * clocks or actual timers outside of the mocking environment. + * @since v20.4.0 + */ + runAll(): void; + /** + * Calls {@link MockTimers.reset()}. + */ + [Symbol.dispose](): void; + } /** - * The duration of the test in milliseconds. + * An object whose methods are used to configure available assertions on the + * `TestContext` objects in the current process. The methods from `node:assert` + * and snapshot testing functions are available by default. + * + * It is possible to apply the same configuration to all files by placing common + * configuration code in a module + * preloaded with `--require` or `--import`. + * @since v22.14.0 */ - duration_ms: number; + namespace assert { + /** + * Defines a new assertion function with the provided name and function. If an + * assertion already exists with the same name, it is overwritten. + * @since v22.14.0 + */ + function register(name: string, fn: (this: TestContext, ...args: any[]) => void): void; + } /** - * The type of the test, used to denote whether this is a suite. - * @since 20.0.0, 19.9.0, 18.17.0 + * @since v22.3.0 */ - type?: "suite"; - }; - /** - * The test name. - */ - name: string; - /** - * The nesting level of the test. - */ - nesting: number; - /** - * The ordinal number of the test. - */ - testNumber: number; - /** - * Present if `context.todo` is called. - */ - todo?: string | boolean; - /** - * Present if `context.skip` is called. - */ - skip?: string | boolean; -} -interface TestPlan extends TestLocationInfo { - /** - * The nesting level of the test. - */ - nesting: number; - /** - * The number of subtests that have ran. - */ - count: number; -} -interface TestStart extends TestLocationInfo { - /** - * The test name. - */ - name: string; - /** - * The nesting level of the test. - */ - nesting: number; -} -interface TestStderr { - /** - * The path of the test file. - */ - file: string; - /** - * The message written to `stderr`. - */ - message: string; -} -interface TestStdout { - /** - * The path of the test file. - */ - file: string; - /** - * The message written to `stdout`. - */ - message: string; + namespace snapshot { + /** + * This function is used to customize the default serialization mechanism used by the test runner. + * + * By default, the test runner performs serialization by calling `JSON.stringify(value, null, 2)` on the provided value. + * `JSON.stringify()` does have limitations regarding circular structures and supported data types. + * If a more robust serialization mechanism is required, this function should be used to specify a list of custom serializers. + * + * Serializers are called in order, with the output of the previous serializer passed as input to the next. + * The final result must be a string value. + * @since v22.3.0 + * @param serializers An array of synchronous functions used as the default serializers for snapshot tests. + */ + function setDefaultSnapshotSerializers(serializers: ReadonlyArray<(value: any) => any>): void; + /** + * This function is used to set a custom resolver for the location of the snapshot file used for snapshot testing. + * By default, the snapshot filename is the same as the entry point filename with `.snapshot` appended. + * @since v22.3.0 + * @param fn A function used to compute the location of the snapshot file. + * The function receives the path of the test file as its only argument. If the + * test is not associated with a file (for example in the REPL), the input is + * undefined. `fn()` must return a string specifying the location of the snapshot file. + */ + function setResolveSnapshotPath(fn: (path: string | undefined) => string): void; + } + } + type FunctionPropertyNames = { + [K in keyof T]: T[K] extends Function ? K : never; + }[keyof T]; + export = test; } /** @@ -2036,19 +2121,21 @@ interface TestStdout { */ declare module "node:test/reporters" { import { Transform, TransformOptions } from "node:stream"; + import { EventData } from "node:test"; type TestEvent = - | { type: "test:coverage"; data: TestCoverage } - | { type: "test:complete"; data: TestComplete } - | { type: "test:dequeue"; data: TestDequeue } - | { type: "test:diagnostic"; data: DiagnosticData } - | { type: "test:enqueue"; data: TestEnqueue } - | { type: "test:fail"; data: TestFail } - | { type: "test:pass"; data: TestPass } - | { type: "test:plan"; data: TestPlan } - | { type: "test:start"; data: TestStart } - | { type: "test:stderr"; data: TestStderr } - | { type: "test:stdout"; data: TestStdout } + | { type: "test:coverage"; data: EventData.TestCoverage } + | { type: "test:complete"; data: EventData.TestComplete } + | { type: "test:dequeue"; data: EventData.TestDequeue } + | { type: "test:diagnostic"; data: EventData.TestDiagnostic } + | { type: "test:enqueue"; data: EventData.TestEnqueue } + | { type: "test:fail"; data: EventData.TestFail } + | { type: "test:pass"; data: EventData.TestPass } + | { type: "test:plan"; data: EventData.TestPlan } + | { type: "test:start"; data: EventData.TestStart } + | { type: "test:stderr"; data: EventData.TestStderr } + | { type: "test:stdout"; data: EventData.TestStdout } + | { type: "test:summary"; data: EventData.TestSummary } | { type: "test:watch:drained"; data: undefined }; type TestEventGenerator = AsyncGenerator; @@ -2090,8 +2177,6 @@ declare module "node:test/reporters" { * [`--experimental-test-coverage`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--experimental-test-coverage) flag. * @since v22.0.0 */ - // TODO: change the export to a wrapper function once node@0db38f0 is merged (breaking change) - // const lcov: ReporterConstructorWrapper; const lcov: LcovReporter; export { dot, junit, lcov, spec, tap, TestEvent }; diff --git a/node_modules/@types/node/timers.d.ts b/node_modules/@types/node/timers.d.ts index a4ea3e572..44bc977e9 100644 --- a/node_modules/@types/node/timers.d.ts +++ b/node_modules/@types/node/timers.d.ts @@ -10,12 +10,8 @@ */ declare module "timers" { import { Abortable } from "node:events"; - import { - setImmediate as setImmediatePromise, - setInterval as setIntervalPromise, - setTimeout as setTimeoutPromise, - } from "node:timers/promises"; - interface TimerOptions extends Abortable { + import * as promises from "node:timers/promises"; + export interface TimerOptions extends Abortable { /** * Set to `false` to indicate that the scheduled `Timeout` * should not require the Node.js event loop to remain active. @@ -23,38 +19,33 @@ declare module "timers" { */ ref?: boolean | undefined; } - let setTimeout: typeof global.setTimeout; - let clearTimeout: typeof global.clearTimeout; - let setInterval: typeof global.setInterval; - let clearInterval: typeof global.clearInterval; - let setImmediate: typeof global.setImmediate; - let clearImmediate: typeof global.clearImmediate; global { namespace NodeJS { - // compatibility with older typings - interface Timer extends RefCounted { - hasRef(): boolean; - refresh(): this; - [Symbol.toPrimitive](): number; - } /** * This object is created internally and is returned from `setImmediate()`. It * can be passed to `clearImmediate()` in order to cancel the scheduled * actions. * * By default, when an immediate is scheduled, the Node.js event loop will continue - * running as long as the immediate is active. The `Immediate` object returned by `setImmediate()` exports both `immediate.ref()` and `immediate.unref()` functions that can be used to - * control this default behavior. + * running as long as the immediate is active. The `Immediate` object returned by + * `setImmediate()` exports both `immediate.ref()` and `immediate.unref()` + * functions that can be used to control this default behavior. */ - class Immediate implements RefCounted { + interface Immediate extends RefCounted, Disposable { + /** + * If true, the `Immediate` object will keep the Node.js event loop active. + * @since v11.0.0 + */ + hasRef(): boolean; /** - * When called, requests that the Node.js event loop _not_ exit so long as the `Immediate` is active. Calling `immediate.ref()` multiple times will have no + * When called, requests that the Node.js event loop _not_ exit so long as the + * `Immediate` is active. Calling `immediate.ref()` multiple times will have no * effect. * * By default, all `Immediate` objects are "ref'ed", making it normally unnecessary * to call `immediate.ref()` unless `immediate.unref()` had been called previously. * @since v9.7.0 - * @return a reference to `immediate` + * @returns a reference to `immediate` */ ref(): this; /** @@ -63,53 +54,59 @@ declare module "timers" { * running, the process may exit before the `Immediate` object's callback is * invoked. Calling `immediate.unref()` multiple times will have no effect. * @since v9.7.0 - * @return a reference to `immediate` + * @returns a reference to `immediate` */ unref(): this; - /** - * If true, the `Immediate` object will keep the Node.js event loop active. - * @since v11.0.0 - */ - hasRef(): boolean; - _onImmediate: Function; // to distinguish it from the Timeout class /** * Cancels the immediate. This is similar to calling `clearImmediate()`. - * @since v20.5.0 + * @since v20.5.0, v18.18.0 + * @experimental */ [Symbol.dispose](): void; + _onImmediate(...args: any[]): void; + } + // Legacy interface used in Node.js v9 and prior + // TODO: remove in a future major version bump + /** @deprecated Use `NodeJS.Timeout` instead. */ + interface Timer extends RefCounted { + hasRef(): boolean; + refresh(): this; + [Symbol.toPrimitive](): number; } /** - * This object is created internally and is returned from `setTimeout()` and `setInterval()`. It can be passed to either `clearTimeout()` or `clearInterval()` in order to cancel the - * scheduled actions. + * This object is created internally and is returned from `setTimeout()` and + * `setInterval()`. It can be passed to either `clearTimeout()` or + * `clearInterval()` in order to cancel the scheduled actions. * - * By default, when a timer is scheduled using either `setTimeout()` or `setInterval()`, the Node.js event loop will continue running as long as the + * By default, when a timer is scheduled using either `setTimeout()` or + * `setInterval()`, the Node.js event loop will continue running as long as the * timer is active. Each of the `Timeout` objects returned by these functions * export both `timeout.ref()` and `timeout.unref()` functions that can be used to * control this default behavior. */ - class Timeout implements Timer { - /** - * When called, requests that the Node.js event loop _not_ exit so long as the`Timeout` is active. Calling `timeout.ref()` multiple times will have no effect. - * - * By default, all `Timeout` objects are "ref'ed", making it normally unnecessary - * to call `timeout.ref()` unless `timeout.unref()` had been called previously. - * @since v0.9.1 - * @return a reference to `timeout` - */ - ref(): this; + interface Timeout extends RefCounted, Disposable, Timer { /** - * When called, the active `Timeout` object will not require the Node.js event loop - * to remain active. If there is no other activity keeping the event loop running, - * the process may exit before the `Timeout` object's callback is invoked. Calling `timeout.unref()` multiple times will have no effect. + * Cancels the timeout. * @since v0.9.1 - * @return a reference to `timeout` + * @legacy Use `clearTimeout()` instead. + * @returns a reference to `timeout` */ - unref(): this; + close(): this; /** * If true, the `Timeout` object will keep the Node.js event loop active. * @since v11.0.0 */ hasRef(): boolean; + /** + * When called, requests that the Node.js event loop _not_ exit so long as the + * `Timeout` is active. Calling `timeout.ref()` multiple times will have no effect. + * + * By default, all `Timeout` objects are "ref'ed", making it normally unnecessary + * to call `timeout.ref()` unless `timeout.unref()` had been called previously. + * @since v0.9.1 + * @returns a reference to `timeout` + */ + ref(): this; /** * Sets the timer's start time to the current time, and reschedules the timer to * call its callback at the previously specified duration adjusted to the current @@ -119,121 +116,171 @@ declare module "timers" { * Using this on a timer that has already called its callback will reactivate the * timer. * @since v10.2.0 - * @return a reference to `timeout` + * @returns a reference to `timeout` */ refresh(): this; + /** + * When called, the active `Timeout` object will not require the Node.js event loop + * to remain active. If there is no other activity keeping the event loop running, + * the process may exit before the `Timeout` object's callback is invoked. Calling + * `timeout.unref()` multiple times will have no effect. + * @since v0.9.1 + * @returns a reference to `timeout` + */ + unref(): this; + /** + * Coerce a `Timeout` to a primitive. The primitive can be used to + * clear the `Timeout`. The primitive can only be used in the + * same thread where the timeout was created. Therefore, to use it + * across `worker_threads` it must first be passed to the correct + * thread. This allows enhanced compatibility with browser + * `setTimeout()` and `setInterval()` implementations. + * @since v14.9.0, v12.19.0 + */ [Symbol.toPrimitive](): number; /** * Cancels the timeout. - * @since v20.5.0 + * @since v20.5.0, v18.18.0 + * @experimental */ [Symbol.dispose](): void; + _onTimeout(...args: any[]): void; } } /** - * Schedules execution of a one-time `callback` after `delay` milliseconds. - * - * The `callback` will likely not be invoked in precisely `delay` milliseconds. - * Node.js makes no guarantees about the exact timing of when callbacks will fire, - * nor of their ordering. The callback will be called as close as possible to the - * time specified. + * Schedules the "immediate" execution of the `callback` after I/O events' + * callbacks. * - * When `delay` is larger than `2147483647` or less than `1`, the `delay` will be set to `1`. Non-integer delays are truncated to an integer. + * When multiple calls to `setImmediate()` are made, the `callback` functions are + * queued for execution in the order in which they are created. The entire callback + * queue is processed every event loop iteration. If an immediate timer is queued + * from inside an executing callback, that timer will not be triggered until the + * next event loop iteration. * * If `callback` is not a function, a `TypeError` will be thrown. * - * This method has a custom variant for promises that is available using `timersPromises.setTimeout()`. - * @since v0.0.1 - * @param callback The function to call when the timer elapses. - * @param [delay=1] The number of milliseconds to wait before calling the `callback`. + * This method has a custom variant for promises that is available using + * `timersPromises.setImmediate()`. + * @since v0.9.1 + * @param callback The function to call at the end of this turn of + * the Node.js [Event Loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#setimmediate-vs-settimeout) * @param args Optional arguments to pass when the `callback` is called. - * @return for use with {@link clearTimeout} + * @returns for use with `clearImmediate()` */ - function setTimeout( + function setImmediate( callback: (...args: TArgs) => void, - ms?: number, ...args: TArgs - ): NodeJS.Timeout; - // util.promisify no rest args compability + ): NodeJS.Immediate; + // Allow a single void-accepting argument to be optional in arguments lists. + // Allows usage such as `new Promise(resolve => setTimeout(resolve, ms))` (#54258) // eslint-disable-next-line @typescript-eslint/no-invalid-void-type - function setTimeout(callback: (args: void) => void, ms?: number): NodeJS.Timeout; - namespace setTimeout { - const __promisify__: typeof setTimeoutPromise; + function setImmediate(callback: (_: void) => void): NodeJS.Immediate; + namespace setImmediate { + import __promisify__ = promises.setImmediate; + export { __promisify__ }; } - /** - * Cancels a `Timeout` object created by `setTimeout()`. - * @since v0.0.1 - * @param timeout A `Timeout` object as returned by {@link setTimeout} or the `primitive` of the `Timeout` object as a string or a number. - */ - function clearTimeout(timeoutId: NodeJS.Timeout | string | number | undefined): void; /** * Schedules repeated execution of `callback` every `delay` milliseconds. * - * When `delay` is larger than `2147483647` or less than `1`, the `delay` will be - * set to `1`. Non-integer delays are truncated to an integer. + * When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay` + * will be set to `1`. Non-integer delays are truncated to an integer. * * If `callback` is not a function, a `TypeError` will be thrown. * - * This method has a custom variant for promises that is available using `timersPromises.setInterval()`. + * This method has a custom variant for promises that is available using + * `timersPromises.setInterval()`. * @since v0.0.1 * @param callback The function to call when the timer elapses. - * @param [delay=1] The number of milliseconds to wait before calling the `callback`. + * @param delay The number of milliseconds to wait before calling the + * `callback`. **Default:** `1`. * @param args Optional arguments to pass when the `callback` is called. - * @return for use with {@link clearInterval} + * @returns for use with `clearInterval()` */ function setInterval( callback: (...args: TArgs) => void, - ms?: number, + delay?: number, ...args: TArgs ): NodeJS.Timeout; - // util.promisify no rest args compability + // Allow a single void-accepting argument to be optional in arguments lists. + // Allows usage such as `new Promise(resolve => setTimeout(resolve, ms))` (#54258) // eslint-disable-next-line @typescript-eslint/no-invalid-void-type - function setInterval(callback: (args: void) => void, ms?: number): NodeJS.Timeout; - namespace setInterval { - const __promisify__: typeof setIntervalPromise; - } - /** - * Cancels a `Timeout` object created by `setInterval()`. - * @since v0.0.1 - * @param timeout A `Timeout` object as returned by {@link setInterval} or the `primitive` of the `Timeout` object as a string or a number. - */ - function clearInterval(intervalId: NodeJS.Timeout | string | number | undefined): void; + function setInterval(callback: (_: void) => void, delay?: number): NodeJS.Timeout; /** - * Schedules the "immediate" execution of the `callback` after I/O events' - * callbacks. + * Schedules execution of a one-time `callback` after `delay` milliseconds. * - * When multiple calls to `setImmediate()` are made, the `callback` functions are - * queued for execution in the order in which they are created. The entire callback - * queue is processed every event loop iteration. If an immediate timer is queued - * from inside an executing callback, that timer will not be triggered until the - * next event loop iteration. + * The `callback` will likely not be invoked in precisely `delay` milliseconds. + * Node.js makes no guarantees about the exact timing of when callbacks will fire, + * nor of their ordering. The callback will be called as close as possible to the + * time specified. + * + * When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay` + * will be set to `1`. Non-integer delays are truncated to an integer. * * If `callback` is not a function, a `TypeError` will be thrown. * - * This method has a custom variant for promises that is available using `timersPromises.setImmediate()`. - * @since v0.9.1 - * @param callback The function to call at the end of this turn of the Node.js `Event Loop` + * This method has a custom variant for promises that is available using + * `timersPromises.setTimeout()`. + * @since v0.0.1 + * @param callback The function to call when the timer elapses. + * @param delay The number of milliseconds to wait before calling the + * `callback`. **Default:** `1`. * @param args Optional arguments to pass when the `callback` is called. - * @return for use with {@link clearImmediate} + * @returns for use with `clearTimeout()` */ - function setImmediate( + function setTimeout( callback: (...args: TArgs) => void, + delay?: number, ...args: TArgs - ): NodeJS.Immediate; - // util.promisify no rest args compability + ): NodeJS.Timeout; + // Allow a single void-accepting argument to be optional in arguments lists. + // Allows usage such as `new Promise(resolve => setTimeout(resolve, ms))` (#54258) // eslint-disable-next-line @typescript-eslint/no-invalid-void-type - function setImmediate(callback: (args: void) => void): NodeJS.Immediate; - namespace setImmediate { - const __promisify__: typeof setImmediatePromise; + function setTimeout(callback: (_: void) => void, delay?: number): NodeJS.Timeout; + namespace setTimeout { + import __promisify__ = promises.setTimeout; + export { __promisify__ }; } /** * Cancels an `Immediate` object created by `setImmediate()`. * @since v0.9.1 - * @param immediate An `Immediate` object as returned by {@link setImmediate}. + * @param immediate An `Immediate` object as returned by `setImmediate()`. + */ + function clearImmediate(immediate: NodeJS.Immediate | undefined): void; + /** + * Cancels a `Timeout` object created by `setInterval()`. + * @since v0.0.1 + * @param timeout A `Timeout` object as returned by `setInterval()` + * or the primitive of the `Timeout` object as a string or a number. + */ + function clearInterval(timeout: NodeJS.Timeout | string | number | undefined): void; + /** + * Cancels a `Timeout` object created by `setTimeout()`. + * @since v0.0.1 + * @param timeout A `Timeout` object as returned by `setTimeout()` + * or the primitive of the `Timeout` object as a string or a number. + */ + function clearTimeout(timeout: NodeJS.Timeout | string | number | undefined): void; + /** + * The `queueMicrotask()` method queues a microtask to invoke `callback`. If + * `callback` throws an exception, the `process` object `'uncaughtException'` + * event will be emitted. + * + * The microtask queue is managed by V8 and may be used in a similar manner to + * the `process.nextTick()` queue, which is managed by Node.js. The + * `process.nextTick()` queue is always processed before the microtask queue + * within each turn of the Node.js event loop. + * @since v11.0.0 + * @param callback Function to be queued. */ - function clearImmediate(immediateId: NodeJS.Immediate | undefined): void; function queueMicrotask(callback: () => void): void; } + import clearImmediate = globalThis.clearImmediate; + import clearInterval = globalThis.clearInterval; + import clearTimeout = globalThis.clearTimeout; + import setImmediate = globalThis.setImmediate; + import setInterval = globalThis.setInterval; + import setTimeout = globalThis.setTimeout; + export { clearImmediate, clearInterval, clearTimeout, promises, setImmediate, setInterval, setTimeout }; } declare module "node:timers" { export * from "timers"; diff --git a/node_modules/@types/node/timers/promises.d.ts b/node_modules/@types/node/timers/promises.d.ts index 1e6eb65a2..05db90c65 100644 --- a/node_modules/@types/node/timers/promises.d.ts +++ b/node_modules/@types/node/timers/promises.d.ts @@ -1,6 +1,7 @@ /** * The `timers/promises` API provides an alternative set of timer functions - * that return `Promise` objects. The API is accessible via `import timersPromises from 'node:timers/promises'`. + * that return `Promise` objects. The API is accessible via + * `require('node:timers/promises')`. * * ```js * import { @@ -10,6 +11,7 @@ * } from 'node:timers/promises'; * ``` * @since v15.0.0 + * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/timers/promises.js) */ declare module "timers/promises" { import { TimerOptions } from "node:timers"; @@ -24,7 +26,8 @@ declare module "timers/promises" { * console.log(res); // Prints 'result' * ``` * @since v15.0.0 - * @param [delay=1] The number of milliseconds to wait before fulfilling the promise. + * @param delay The number of milliseconds to wait before fulfilling the + * promise. **Default:** `1`. * @param value A value with which the promise is fulfilled. */ function setTimeout(delay?: number, value?: T, options?: TimerOptions): Promise; @@ -62,33 +65,41 @@ declare module "timers/promises" { * console.log(Date.now()); * ``` * @since v15.9.0 + * @param delay The number of milliseconds to wait between iterations. + * **Default:** `1`. + * @param value A value with which the iterator returns. */ - function setInterval(delay?: number, value?: T, options?: TimerOptions): AsyncIterable; + function setInterval(delay?: number, value?: T, options?: TimerOptions): NodeJS.AsyncIterator; interface Scheduler { /** - * An experimental API defined by the [Scheduling APIs](https://github.com/WICG/scheduling-apis) draft specification being developed as a standard Web Platform API. + * An experimental API defined by the [Scheduling APIs](https://github.com/WICG/scheduling-apis) draft specification + * being developed as a standard Web Platform API. * - * Calling `timersPromises.scheduler.wait(delay, options)` is roughly equivalent to calling `timersPromises.setTimeout(delay, undefined, options)` except that the `ref` - * option is not supported. + * Calling `timersPromises.scheduler.wait(delay, options)` is roughly equivalent + * to calling `timersPromises.setTimeout(delay, undefined, options)` except that + * the `ref` option is not supported. * * ```js * import { scheduler } from 'node:timers/promises'; * * await scheduler.wait(1000); // Wait one second before continuing * ``` - * @since v16.14.0 + * @since v17.3.0, v16.14.0 * @experimental - * @param [delay=1] The number of milliseconds to wait before fulfilling the promise. + * @param delay The number of milliseconds to wait before resolving the + * promise. */ - wait: (delay?: number, options?: Pick) => Promise; + wait(delay: number, options?: { signal?: AbortSignal }): Promise; /** - * An experimental API defined by the [Scheduling APIs](https://nodejs.org/docs/latest-v20.x/api/async_hooks.html#promise-execution-tracking) draft specification + * An experimental API defined by the [Scheduling APIs](https://github.com/WICG/scheduling-apis) draft specification * being developed as a standard Web Platform API. - * Calling `timersPromises.scheduler.yield()` is equivalent to calling `timersPromises.setImmediate()` with no arguments. - * @since v16.14.0 + * + * Calling `timersPromises.scheduler.yield()` is equivalent to calling + * `timersPromises.setImmediate()` with no arguments. + * @since v17.3.0, v16.14.0 * @experimental */ - yield: () => Promise; + yield(): Promise; } const scheduler: Scheduler; } diff --git a/node_modules/@types/node/tls.d.ts b/node_modules/@types/node/tls.d.ts index ee81ba21f..96540a34b 100644 --- a/node_modules/@types/node/tls.d.ts +++ b/node_modules/@types/node/tls.d.ts @@ -398,6 +398,14 @@ declare module "tls" { }, callback: (err: Error | null) => void, ): undefined | boolean; + /** + * The `tlsSocket.setKeyCert()` method sets the private key and certificate to use for the socket. + * This is mainly useful if you wish to select a server certificate from a TLS server's `ALPNCallback`. + * @since v22.5.0, v20.17.0 + * @param context An object containing at least `key` and `cert` properties from the {@link createSecureContext()} `options`, + * or a TLS context object created with {@link createSecureContext()} itself. + */ + setKeyCert(context: SecureContextOptions | SecureContext): void; /** * The `tlsSocket.setMaxSendFragment()` method sets the maximum TLS fragment size. * Returns `true` if setting the limit succeeded; `false` otherwise. @@ -639,7 +647,7 @@ declare module "tls" { * @param context An object containing any of the possible properties from the {@link createSecureContext} `options` arguments (e.g. `key`, `cert`, `ca`, etc), or a TLS context object created * with {@link createSecureContext} itself. */ - addContext(hostname: string, context: SecureContextOptions): void; + addContext(hostname: string, context: SecureContextOptions | SecureContext): void; /** * Returns the session ticket keys. * @@ -809,6 +817,12 @@ declare module "tls" { * This option cannot be used with the `ALPNProtocols` option, and setting both options will throw an error. */ ALPNCallback?: ((arg: { servername: string; protocols: string[] }) => string | undefined) | undefined; + /** + * Treat intermediate (non-self-signed) + * certificates in the trust CA certificate list as trusted. + * @since v22.9.0, v20.18.0 + */ + allowPartialTrustChain?: boolean | undefined; /** * Optionally override the trusted CA certificates. Default is to trust * the well-known CAs curated by Mozilla. Mozilla's CAs are completely @@ -1152,6 +1166,31 @@ declare module "tls" { * @since v0.11.13 */ function createSecureContext(options?: SecureContextOptions): SecureContext; + /** + * Returns an array containing the CA certificates from various sources, depending on `type`: + * + * * `"default"`: return the CA certificates that will be used by the Node.js TLS clients by default. + * * When `--use-bundled-ca` is enabled (default), or `--use-openssl-ca` is not enabled, + * this would include CA certificates from the bundled Mozilla CA store. + * * When `--use-system-ca` is enabled, this would also include certificates from the system's + * trusted store. + * * When `NODE_EXTRA_CA_CERTS` is used, this would also include certificates loaded from the specified + * file. + * * `"system"`: return the CA certificates that are loaded from the system's trusted store, according + * to rules set by `--use-system-ca`. This can be used to get the certificates from the system + * when `--use-system-ca` is not enabled. + * * `"bundled"`: return the CA certificates from the bundled Mozilla CA store. This would be the same + * as `tls.rootCertificates`. + * * `"extra"`: return the CA certificates loaded from `NODE_EXTRA_CA_CERTS`. It's an empty array if + * `NODE_EXTRA_CA_CERTS` is not set. + * @since v22.15.0 + * @param type The type of CA certificates that will be returned. Valid values + * are `"default"`, `"system"`, `"bundled"` and `"extra"`. + * **Default:** `"default"`. + * @returns An array of PEM-encoded certificates. The array may contain duplicates + * if the same certificate is repeatedly stored in multiple sources. + */ + function getCACertificates(type?: "default" | "system" | "bundled" | "extra"): string[]; /** * Returns an array with the names of the supported TLS ciphers. The names are * lower-case for historical reasons, but must be uppercased to be used in diff --git a/node_modules/@types/node/ts5.6/buffer.buffer.d.ts b/node_modules/@types/node/ts5.6/buffer.buffer.d.ts index 21f72115c..d19026dc2 100644 --- a/node_modules/@types/node/ts5.6/buffer.buffer.d.ts +++ b/node_modules/@types/node/ts5.6/buffer.buffer.d.ts @@ -24,7 +24,7 @@ declare module "buffer" { * @param array The octets to store. * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead. */ - new(array: Uint8Array): Buffer; + new(array: ArrayLike): Buffer; /** * Produces a Buffer backed by the same allocated memory as * the given {ArrayBuffer}/{SharedArrayBuffer}. @@ -33,20 +33,6 @@ declare module "buffer" { * @deprecated since v10.0.0 - Use `Buffer.from(arrayBuffer[, byteOffset[, length]])` instead. */ new(arrayBuffer: ArrayBuffer | SharedArrayBuffer): Buffer; - /** - * Allocates a new buffer containing the given {array} of octets. - * - * @param array The octets to store. - * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead. - */ - new(array: readonly any[]): Buffer; - /** - * Copies the passed {buffer} data onto a new {Buffer} instance. - * - * @param buffer The buffer to copy. - * @deprecated since v10.0.0 - Use `Buffer.from(buffer)` instead. - */ - new(buffer: Buffer): Buffer; /** * Allocates a new `Buffer` using an `array` of bytes in the range `0` – `255`. * Array entries outside that range will be truncated to fit into it. @@ -58,40 +44,121 @@ declare module "buffer" { * const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); * ``` * - * If `array` is an `Array`\-like object (that is, one with a `length` property of + * If `array` is an `Array`-like object (that is, one with a `length` property of * type `number`), it is treated as if it is an array, unless it is a `Buffer` or - * a `Uint8Array`. This means all other `TypedArray` variants get treated as an `Array`. To create a `Buffer` from the bytes backing a `TypedArray`, use `Buffer.copyBytesFrom()`. + * a `Uint8Array`. This means all other `TypedArray` variants get treated as an + * `Array`. To create a `Buffer` from the bytes backing a `TypedArray`, use + * `Buffer.copyBytesFrom()`. * * A `TypeError` will be thrown if `array` is not an `Array` or another type * appropriate for `Buffer.from()` variants. * - * `Buffer.from(array)` and `Buffer.from(string)` may also use the internal `Buffer` pool like `Buffer.allocUnsafe()` does. + * `Buffer.from(array)` and `Buffer.from(string)` may also use the internal + * `Buffer` pool like `Buffer.allocUnsafe()` does. * @since v5.10.0 */ + from(array: WithImplicitCoercion>): Buffer; + /** + * This creates a view of the `ArrayBuffer` without copying the underlying + * memory. For example, when passed a reference to the `.buffer` property of a + * `TypedArray` instance, the newly created `Buffer` will share the same + * allocated memory as the `TypedArray`'s underlying `ArrayBuffer`. + * + * ```js + * import { Buffer } from 'node:buffer'; + * + * const arr = new Uint16Array(2); + * + * arr[0] = 5000; + * arr[1] = 4000; + * + * // Shares memory with `arr`. + * const buf = Buffer.from(arr.buffer); + * + * console.log(buf); + * // Prints: + * + * // Changing the original Uint16Array changes the Buffer also. + * arr[1] = 6000; + * + * console.log(buf); + * // Prints: + * ``` + * + * The optional `byteOffset` and `length` arguments specify a memory range within + * the `arrayBuffer` that will be shared by the `Buffer`. + * + * ```js + * import { Buffer } from 'node:buffer'; + * + * const ab = new ArrayBuffer(10); + * const buf = Buffer.from(ab, 0, 2); + * + * console.log(buf.length); + * // Prints: 2 + * ``` + * + * A `TypeError` will be thrown if `arrayBuffer` is not an `ArrayBuffer` or a + * `SharedArrayBuffer` or another type appropriate for `Buffer.from()` + * variants. + * + * It is important to remember that a backing `ArrayBuffer` can cover a range + * of memory that extends beyond the bounds of a `TypedArray` view. A new + * `Buffer` created using the `buffer` property of a `TypedArray` may extend + * beyond the range of the `TypedArray`: + * + * ```js + * import { Buffer } from 'node:buffer'; + * + * const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 elements + * const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 elements + * console.log(arrA.buffer === arrB.buffer); // true + * + * const buf = Buffer.from(arrB.buffer); + * console.log(buf); + * // Prints: + * ``` + * @since v5.10.0 + * @param arrayBuffer An `ArrayBuffer`, `SharedArrayBuffer`, for example the + * `.buffer` property of a `TypedArray`. + * @param byteOffset Index of first byte to expose. **Default:** `0`. + * @param length Number of bytes to expose. **Default:** + * `arrayBuffer.byteLength - byteOffset`. + */ from( arrayBuffer: WithImplicitCoercion, byteOffset?: number, length?: number, ): Buffer; /** - * Creates a new Buffer using the passed {data} - * @param data data to create a new Buffer - */ - from(data: Uint8Array | readonly number[]): Buffer; - from(data: WithImplicitCoercion): Buffer; - /** - * Creates a new Buffer containing the given JavaScript string {str}. - * If provided, the {encoding} parameter identifies the character encoding. - * If not provided, {encoding} defaults to 'utf8'. + * Creates a new `Buffer` containing `string`. The `encoding` parameter identifies + * the character encoding to be used when converting `string` into bytes. + * + * ```js + * import { Buffer } from 'node:buffer'; + * + * const buf1 = Buffer.from('this is a tést'); + * const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex'); + * + * console.log(buf1.toString()); + * // Prints: this is a tést + * console.log(buf2.toString()); + * // Prints: this is a tést + * console.log(buf1.toString('latin1')); + * // Prints: this is a tést + * ``` + * + * A `TypeError` will be thrown if `string` is not a string or another type + * appropriate for `Buffer.from()` variants. + * + * `Buffer.from(string)` may also use the internal `Buffer` pool like + * `Buffer.allocUnsafe()` does. + * @since v5.10.0 + * @param string A string to encode. + * @param encoding The encoding of `string`. **Default:** `'utf8'`. */ - from( - str: - | WithImplicitCoercion - | { - [Symbol.toPrimitive](hint: "string"): string; - }, - encoding?: BufferEncoding, - ): Buffer; + from(string: WithImplicitCoercion, encoding?: BufferEncoding): Buffer; + from(arrayOrString: WithImplicitCoercion | string>): Buffer; /** * Creates a new Buffer using the passed {data} * @param values to create a new Buffer @@ -381,5 +448,13 @@ declare module "buffer" { */ subarray(start?: number, end?: number): Buffer; } + type NonSharedBuffer = Buffer; + type AllowSharedBuffer = Buffer; } + /** @deprecated Use `Buffer.allocUnsafeSlow()` instead. */ + var SlowBuffer: { + /** @deprecated Use `Buffer.allocUnsafeSlow()` instead. */ + new(size: number): Buffer; + prototype: Buffer; + }; } diff --git a/node_modules/@types/node/url.d.ts b/node_modules/@types/node/url.d.ts index 72232c7a2..b1f84d98a 100644 --- a/node_modules/@types/node/url.d.ts +++ b/node_modules/@types/node/url.d.ts @@ -420,14 +420,12 @@ declare module "url" { * Threads, `Blob` objects registered within one Worker will not be available * to other workers or the main thread. * @since v16.7.0 - * @experimental */ static createObjectURL(blob: NodeBlob): string; /** * Removes the stored `Blob` identified by the given ID. Attempting to revoke a * ID that isn't registered will silently fail. * @since v16.7.0 - * @experimental * @param id A `'blob:nodedata:...` URL string returned by a prior call to `URL.createObjectURL()`. */ static revokeObjectURL(id: string): void; @@ -828,7 +826,7 @@ declare module "url" { * Returns an ES6 `Iterator` over each of the name-value pairs in the query. * Each item of the iterator is a JavaScript `Array`. The first item of the `Array` is the `name`, the second item of the `Array` is the `value`. * - * Alias for `urlSearchParams[@@iterator]()`. + * Alias for `urlSearchParams[Symbol.iterator]()`. */ entries(): URLSearchParamsIterator<[string, string]>; /** diff --git a/node_modules/@types/node/util.d.ts b/node_modules/@types/node/util.d.ts index 19aeb232a..68c624dbe 100644 --- a/node_modules/@types/node/util.d.ts +++ b/node_modules/@types/node/util.d.ts @@ -108,6 +108,83 @@ declare module "util" { export interface InspectOptionsStylized extends InspectOptions { stylize(text: string, styleType: Style): string; } + export interface CallSiteObject { + /** + * Returns the name of the function associated with this call site. + */ + functionName: string; + /** + * Returns the name of the resource that contains the script for the + * function for this call site. + */ + scriptName: string; + /** + * Returns the unique id of the script, as in Chrome DevTools protocol + * [`Runtime.ScriptId`](https://chromedevtools.github.io/devtools-protocol/1-3/Runtime/#type-ScriptId). + * @since v22.14.0 + */ + scriptId: string; + /** + * Returns the number, 1-based, of the line for the associate function call. + */ + lineNumber: number; + /** + * Returns the 1-based column offset on the line for the associated function call. + */ + columnNumber: number; + } + export type DiffEntry = [operation: -1 | 0 | 1, value: string]; + /** + * `util.diff()` compares two string or array values and returns an array of difference entries. + * It uses the Myers diff algorithm to compute minimal differences, which is the same algorithm + * used internally by assertion error messages. + * + * If the values are equal, an empty array is returned. + * + * ```js + * const { diff } = require('node:util'); + * + * // Comparing strings + * const actualString = '12345678'; + * const expectedString = '12!!5!7!'; + * console.log(diff(actualString, expectedString)); + * // [ + * // [0, '1'], + * // [0, '2'], + * // [1, '3'], + * // [1, '4'], + * // [-1, '!'], + * // [-1, '!'], + * // [0, '5'], + * // [1, '6'], + * // [-1, '!'], + * // [0, '7'], + * // [1, '8'], + * // [-1, '!'], + * // ] + * // Comparing arrays + * const actualArray = ['1', '2', '3']; + * const expectedArray = ['1', '3', '4']; + * console.log(diff(actualArray, expectedArray)); + * // [ + * // [0, '1'], + * // [1, '2'], + * // [0, '3'], + * // [-1, '4'], + * // ] + * // Equal values return empty array + * console.log(diff('same', 'same')); + * // [] + * ``` + * @since v22.15.0 + * @experimental + * @param actual The first value to compare + * @param expected The second value to compare + * @returns An array of difference entries. Each entry is an array with two elements: + * * Index 0: `number` Operation code: `-1` for delete, `0` for no-op/unchanged, `1` for insert + * * Index 1: `string` The value associated with the operation + */ + export function diff(actual: string | readonly string[], expected: string | readonly string[]): DiffEntry[]; /** * The `util.format()` method returns a formatted string using the first argument * as a `printf`-like format string which can contain zero or more format @@ -166,6 +243,87 @@ declare module "util" { * @since v10.0.0 */ export function formatWithOptions(inspectOptions: InspectOptions, format?: any, ...param: any[]): string; + interface GetCallSitesOptions { + /** + * Reconstruct the original location in the stacktrace from the source-map. + * Enabled by default with the flag `--enable-source-maps`. + */ + sourceMap?: boolean | undefined; + } + /** + * Returns an array of call site objects containing the stack of + * the caller function. + * + * ```js + * import { getCallSites } from 'node:util'; + * + * function exampleFunction() { + * const callSites = getCallSites(); + * + * console.log('Call Sites:'); + * callSites.forEach((callSite, index) => { + * console.log(`CallSite ${index + 1}:`); + * console.log(`Function Name: ${callSite.functionName}`); + * console.log(`Script Name: ${callSite.scriptName}`); + * console.log(`Line Number: ${callSite.lineNumber}`); + * console.log(`Column Number: ${callSite.column}`); + * }); + * // CallSite 1: + * // Function Name: exampleFunction + * // Script Name: /home/example.js + * // Line Number: 5 + * // Column Number: 26 + * + * // CallSite 2: + * // Function Name: anotherFunction + * // Script Name: /home/example.js + * // Line Number: 22 + * // Column Number: 3 + * + * // ... + * } + * + * // A function to simulate another stack layer + * function anotherFunction() { + * exampleFunction(); + * } + * + * anotherFunction(); + * ``` + * + * It is possible to reconstruct the original locations by setting the option `sourceMap` to `true`. + * If the source map is not available, the original location will be the same as the current location. + * When the `--enable-source-maps` flag is enabled, for example when using `--experimental-transform-types`, + * `sourceMap` will be true by default. + * + * ```ts + * import { getCallSites } from 'node:util'; + * + * interface Foo { + * foo: string; + * } + * + * const callSites = getCallSites({ sourceMap: true }); + * + * // With sourceMap: + * // Function Name: '' + * // Script Name: example.js + * // Line Number: 7 + * // Column Number: 26 + * + * // Without sourceMap: + * // Function Name: '' + * // Script Name: example.js + * // Line Number: 2 + * // Column Number: 26 + * ``` + * @param frameCount Number of frames to capture as call site objects. + * **Default:** `10`. Allowable range is between 1 and 200. + * @return An array of call site objects + * @since v22.9.0 + */ + export function getCallSites(frameCount?: number, options?: GetCallSitesOptions): CallSiteObject[]; + export function getCallSites(options: GetCallSitesOptions): CallSiteObject[]; /** * Returns the string name for a numeric error code that comes from a Node.js API. * The mapping between error codes and error names is platform-dependent. @@ -195,6 +353,20 @@ declare module "util" { * @since v16.0.0, v14.17.0 */ export function getSystemErrorMap(): Map; + /** + * Returns the string message for a numeric error code that comes from a Node.js + * API. + * The mapping between error codes and string messages is platform-dependent. + * + * ```js + * fs.access('file/that/does/not/exist', (err) => { + * const message = util.getSystemErrorMessage(err.errno); + * console.error(message); // no such file or directory + * }); + * ``` + * @since v22.12.0 + */ + export function getSystemErrorMessage(err: number): string; /** * The `util.log()` method prints the given `string` to `stdout` with an included * timestamp. @@ -219,7 +391,6 @@ declare module "util" { * Creates and returns an `AbortController` instance whose `AbortSignal` is marked * as transferable and can be used with `structuredClone()` or `postMessage()`. * @since v18.11.0 - * @experimental * @returns A transferable AbortController */ export function transferableAbortController(): AbortController; @@ -232,41 +403,49 @@ declare module "util" { * channel.port2.postMessage(signal, [signal]); * ``` * @since v18.11.0 - * @experimental * @param signal The AbortSignal * @returns The same AbortSignal */ export function transferableAbortSignal(signal: AbortSignal): AbortSignal; /** - * Listens to abort event on the provided `signal` and - * returns a promise that is fulfilled when the `signal` is - * aborted. If the passed `resource` is garbage collected before the `signal` is - * aborted, the returned promise shall remain pending indefinitely. + * Listens to abort event on the provided `signal` and returns a promise that resolves when the `signal` is aborted. + * If `resource` is provided, it weakly references the operation's associated object, + * so if `resource` is garbage collected before the `signal` aborts, + * then returned promise shall remain pending. + * This prevents memory leaks in long-running or non-cancelable operations. * * ```js * import { aborted } from 'node:util'; * + * // Obtain an object with an abortable signal, like a custom resource or operation. * const dependent = obtainSomethingAbortable(); * + * // Pass `dependent` as the resource, indicating the promise should only resolve + * // if `dependent` is still in memory when the signal is aborted. * aborted(dependent.signal, dependent).then(() => { - * // Do something when dependent is aborted. + * // This code runs when `dependent` is aborted. + * console.log('Dependent resource was aborted.'); * }); * + * // Simulate an event that triggers the abort. * dependent.on('event', () => { - * dependent.abort(); + * dependent.abort(); // This will cause the `aborted` promise to resolve. * }); * ``` * @since v19.7.0 - * @experimental - * @param resource Any non-null entity, reference to which is held weakly. + * @param resource Any non-null object tied to the abortable operation and held weakly. + * If `resource` is garbage collected before the `signal` aborts, the promise remains pending, + * allowing Node.js to stop tracking it. + * This helps prevent memory leaks in long-running or non-cancelable operations. */ export function aborted(signal: AbortSignal, resource: any): Promise; /** * The `util.inspect()` method returns a string representation of `object` that is * intended for debugging. The output of `util.inspect` may change at any time * and should not be depended upon programmatically. Additional `options` may be - * passed that alter the result. `util.inspect()` will use the constructor's name and/or `@@toStringTag` to make - * an identifiable tag for an inspected value. + * passed that alter the result. + * `util.inspect()` will use the constructor's name and/or `Symbol.toStringTag` + * property to make an identifiable tag for an inspected value. * * ```js * class Foo { @@ -313,7 +492,7 @@ declare module "util" { * The following example highlights the effect of the `compact` option: * * ```js - * import util from 'node:util'; + * import { inspect } from 'node:util'; * * const o = { * a: [1, 2, [[ @@ -323,7 +502,7 @@ declare module "util" { * 'foo']], 4], * b: new Map([['za', 1], ['zb', 'test']]), * }; - * console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 })); + * console.log(inspect(o, { compact: true, depth: 5, breakLength: 80 })); * * // { a: * // [ 1, @@ -335,7 +514,7 @@ declare module "util" { * // b: Map(2) { 'za' => 1, 'zb' => 'test' } } * * // Setting `compact` to false or an integer creates more reader friendly output. - * console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 })); + * console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 })); * * // { * // a: [ @@ -362,11 +541,10 @@ declare module "util" { * // single line. * ``` * - * The `showHidden` option allows [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) and - * [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) entries to be + * The `showHidden` option allows `WeakMap` and `WeakSet` entries to be * inspected. If there are more entries than `maxArrayLength`, there is no - * guarantee which entries are displayed. That means retrieving the same [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) entries twice may - * result in different output. Furthermore, entries + * guarantee which entries are displayed. That means retrieving the same + * `WeakSet` entries twice may result in different output. Furthermore, entries * with no remaining strong references may be garbage collected at any time. * * ```js @@ -414,10 +592,10 @@ declare module "util" { * ```js * import { inspect } from 'node:util'; * - * const thousand = 1_000; - * const million = 1_000_000; - * const bigNumber = 123_456_789n; - * const bigDecimal = 1_234.123_45; + * const thousand = 1000; + * const million = 1000000; + * const bigNumber = 123456789n; + * const bigDecimal = 1234.12345; * * console.log(inspect(thousand, { numericSeparator: true })); * // 1_000 @@ -538,19 +716,23 @@ declare module "util" { */ export function isError(object: unknown): object is Error; /** - * Usage of `util.inherits()` is discouraged. Please use the ES6 `class` and `extends` keywords to get language level inheritance support. Also note + * Usage of `util.inherits()` is discouraged. Please use the ES6 `class` and + * `extends` keywords to get language level inheritance support. Also note * that the two styles are [semantically incompatible](https://github.com/nodejs/node/issues/4179). * - * Inherit the prototype methods from one [constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) into another. The - * prototype of `constructor` will be set to a new object created from `superConstructor`. + * Inherit the prototype methods from one + * [constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) into another. The + * prototype of `constructor` will be set to a new object created from + * `superConstructor`. * - * This mainly adds some input validation on top of`Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)`. + * This mainly adds some input validation on top of + * `Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)`. * As an additional convenience, `superConstructor` will be accessible * through the `constructor.super_` property. * * ```js - * import util from 'node:util'; - * import EventEmitter from 'node:events'; + * const util = require('node:util'); + * const EventEmitter = require('node:events'); * * function MyStream() { * EventEmitter.call(this); @@ -597,18 +779,42 @@ declare module "util" { export function inherits(constructor: unknown, superConstructor: unknown): void; export type DebugLoggerFunction = (msg: string, ...param: unknown[]) => void; export interface DebugLogger extends DebugLoggerFunction { + /** + * The `util.debuglog().enabled` getter is used to create a test that can be used + * in conditionals based on the existence of the `NODE_DEBUG` environment variable. + * If the `section` name appears within the value of that environment variable, + * then the returned value will be `true`. If not, then the returned value will be + * `false`. + * + * ```js + * import { debuglog } from 'node:util'; + * const enabled = debuglog('foo').enabled; + * if (enabled) { + * console.log('hello from foo [%d]', 123); + * } + * ``` + * + * If this program is run with `NODE_DEBUG=foo` in the environment, then it will + * output something like: + * + * ```console + * hello from foo [123] + * ``` + */ enabled: boolean; } /** * The `util.debuglog()` method is used to create a function that conditionally - * writes debug messages to `stderr` based on the existence of the `NODE_DEBUG`environment variable. If the `section` name appears within the value of that - * environment variable, then the returned function operates similar to `console.error()`. If not, then the returned function is a no-op. + * writes debug messages to `stderr` based on the existence of the `NODE_DEBUG` + * environment variable. If the `section` name appears within the value of that + * environment variable, then the returned function operates similar to + * `console.error()`. If not, then the returned function is a no-op. * * ```js - * import util from 'node:util'; - * const debuglog = util.debuglog('foo'); + * import { debuglog } from 'node:util'; + * const log = debuglog('foo'); * - * debuglog('hello from foo [%d]', 123); + * log('hello from foo [%d]', 123); * ``` * * If this program is run with `NODE_DEBUG=foo` in the environment, then @@ -624,10 +830,10 @@ declare module "util" { * The `section` supports wildcard also: * * ```js - * import util from 'node:util'; - * const debuglog = util.debuglog('foo-bar'); + * import { debuglog } from 'node:util'; + * const log = debuglog('foo'); * - * debuglog('hi there, it\'s foo-bar [%d]', 2333); + * log('hi there, it\'s foo-bar [%d]', 2333); * ``` * * if it is run with `NODE_DEBUG=foo*` in the environment, then it will output @@ -637,18 +843,19 @@ declare module "util" { * FOO-BAR 3257: hi there, it's foo-bar [2333] * ``` * - * Multiple comma-separated `section` names may be specified in the `NODE_DEBUG`environment variable: `NODE_DEBUG=fs,net,tls`. + * Multiple comma-separated `section` names may be specified in the `NODE_DEBUG` + * environment variable: `NODE_DEBUG=fs,net,tls`. * * The optional `callback` argument can be used to replace the logging function * with a different function that doesn't have any initialization or * unnecessary wrapping. * * ```js - * import util from 'node:util'; - * let debuglog = util.debuglog('internals', (debug) => { + * import { debuglog } from 'node:util'; + * let log = debuglog('internals', (debug) => { * // Replace with a logging function that optimizes out * // testing if the section is enabled - * debuglog = debug; + * log = debug; * }); * ``` * @since v0.11.3 @@ -657,7 +864,7 @@ declare module "util" { * @return The logging function */ export function debuglog(section: string, callback?: (fn: DebugLoggerFunction) => void): DebugLogger; - export const debug: typeof debuglog; + export { debuglog as debug }; /** * Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`. * @@ -874,14 +1081,15 @@ declare module "util" { * such a way that it is marked as deprecated. * * ```js - * import util from 'node:util'; + * import { deprecate } from 'node:util'; * - * exports.obsoleteFunction = util.deprecate(() => { + * export const obsoleteFunction = deprecate(() => { * // Do something here. * }, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.'); * ``` * - * When called, `util.deprecate()` will return a function that will emit a `DeprecationWarning` using the `'warning'` event. The warning will + * When called, `util.deprecate()` will return a function that will emit a + * `DeprecationWarning` using the `'warning'` event. The warning will * be emitted and printed to `stderr` the first time the returned function is * called. After the warning is emitted, the wrapped function is called without * emitting a warning. @@ -890,16 +1098,24 @@ declare module "util" { * the warning will be emitted only once for that `code`. * * ```js - * import util from 'node:util'; + * import { deprecate } from 'node:util'; * - * const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001'); - * const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001'); + * const fn1 = deprecate( + * () => 'a value', + * 'deprecation message', + * 'DEP0001', + * ); + * const fn2 = deprecate( + * () => 'a different value', + * 'other dep message', + * 'DEP0001', + * ); * fn1(); // Emits a deprecation warning with code DEP0001 * fn2(); // Does not emit a deprecation warning because it has the same code * ``` * * If either the `--no-deprecation` or `--no-warnings` command-line flags are - * used, or if the `process.noDeprecation` property is set to `true`_prior_ to + * used, or if the `process.noDeprecation` property is set to `true` _prior_ to * the first deprecation warning, the `util.deprecate()` method does nothing. * * If the `--trace-deprecation` or `--trace-warnings` command-line flags are set, @@ -907,10 +1123,13 @@ declare module "util" { * stack trace are printed to `stderr` the first time the deprecated function is * called. * - * If the `--throw-deprecation` command-line flag is set, or the `process.throwDeprecation` property is set to `true`, then an exception will be + * If the `--throw-deprecation` command-line flag is set, or the + * `process.throwDeprecation` property is set to `true`, then an exception will be * thrown when the deprecated function is called. * - * The `--throw-deprecation` command-line flag and `process.throwDeprecation` property take precedence over `--trace-deprecation` and `process.traceDeprecation`. + * The `--throw-deprecation` command-line flag and `process.throwDeprecation` + * property take precedence over `--trace-deprecation` and + * `process.traceDeprecation`. * @since v0.8.0 * @param fn The function that is being deprecated. * @param msg A warning message to display when the deprecated function is invoked. @@ -941,15 +1160,16 @@ declare module "util" { * Takes an `async` function (or a function that returns a `Promise`) and returns a * function following the error-first callback style, i.e. taking * an `(err, value) => ...` callback as the last argument. In the callback, the - * first argument will be the rejection reason (or `null` if the `Promise` resolved), and the second argument will be the resolved value. + * first argument will be the rejection reason (or `null` if the `Promise` + * resolved), and the second argument will be the resolved value. * * ```js - * import util from 'node:util'; + * import { callbackify } from 'node:util'; * * async function fn() { * return 'hello world'; * } - * const callbackFunction = util.callbackify(fn); + * const callbackFunction = callbackify(fn); * * callbackFunction((err, ret) => { * if (err) throw err; @@ -964,11 +1184,13 @@ declare module "util" { * ``` * * The callback is executed asynchronously, and will have a limited stack trace. - * If the callback throws, the process will emit an `'uncaughtException'` event, and if not handled will exit. + * If the callback throws, the process will emit an `'uncaughtException'` + * event, and if not handled will exit. * * Since `null` has a special meaning as the first argument to a callback, if a * wrapped function rejects a `Promise` with a falsy value as a reason, the value - * is wrapped in an `Error` with the original value stored in a field named `reason`. + * is wrapped in an `Error` with the original value stored in a field named + * `reason`. * * ```js * function fn() { @@ -979,7 +1201,7 @@ declare module "util" { * callbackFunction((err, ret) => { * // When the Promise was rejected with `null` it is wrapped with an Error and * // the original value is stored in `reason`. - * err && Object.hasOwn(err, 'reason') && err.reason === null; // true + * err && Object.hasOwn(err, 'reason') && err.reason === null; // true * }); * ``` * @since v8.2.0 @@ -1070,11 +1292,11 @@ declare module "util" { * that returns promises. * * ```js - * import util from 'node:util'; - * import fs from 'node:fs'; + * import { promisify } from 'node:util'; + * import { stat } from 'node:fs'; * - * const stat = util.promisify(fs.stat); - * stat('.').then((stats) => { + * const promisifiedStat = promisify(stat); + * promisifiedStat('.').then((stats) => { * // Do something with `stats` * }).catch((error) => { * // Handle the error. @@ -1084,23 +1306,25 @@ declare module "util" { * Or, equivalently using `async function`s: * * ```js - * import util from 'node:util'; - * import fs from 'node:fs'; + * import { promisify } from 'node:util'; + * import { stat } from 'node:fs'; * - * const stat = util.promisify(fs.stat); + * const promisifiedStat = promisify(stat); * * async function callStat() { - * const stats = await stat('.'); + * const stats = await promisifiedStat('.'); * console.log(`This directory is owned by ${stats.uid}`); * } * * callStat(); * ``` * - * If there is an `original[util.promisify.custom]` property present, `promisify` will return its value, see `Custom promisified functions`. + * If there is an `original[util.promisify.custom]` property present, `promisify` + * will return its value, see [Custom promisified functions](https://nodejs.org/docs/latest-v22.x/api/util.html#custom-promisified-functions). * * `promisify()` assumes that `original` is a function taking a callback as its - * final argument in all cases. If `original` is not a function, `promisify()` will throw an error. If `original` is a function but its last argument is not + * final argument in all cases. If `original` is not a function, `promisify()` + * will throw an error. If `original` is a function but its last argument is not * an error-first callback, it will still be passed an error-first * callback as its last argument. * @@ -1108,7 +1332,7 @@ declare module "util" { * work as expected unless handled specially: * * ```js - * import util from 'node:util'; + * import { promisify } from 'node:util'; * * class Foo { * constructor() { @@ -1122,8 +1346,8 @@ declare module "util" { * * const foo = new Foo(); * - * const naiveBar = util.promisify(foo.bar); - * // TypeError: Cannot read property 'a' of undefined + * const naiveBar = promisify(foo.bar); + * // TypeError: Cannot read properties of undefined (reading 'a') * // naiveBar().then(a => console.log(a)); * * naiveBar.call(foo).then((a) => console.log(a)); // '42' @@ -1186,7 +1410,7 @@ declare module "util" { * @param content The raw contents of a `.env` file. * @since v20.12.0 */ - export function parseEnv(content: string): object; + export function parseEnv(content: string): NodeJS.Dict; // https://nodejs.org/docs/latest/api/util.html#foreground-colors type ForegroundColors = | "black" @@ -1237,22 +1461,47 @@ declare module "util" { | "hidden" | "inverse" | "italic" + | "none" | "overlined" | "reset" | "strikethrough" | "underline"; + export interface StyleTextOptions { + /** + * When true, `stream` is checked to see if it can handle colors. + * @default true + */ + validateStream?: boolean | undefined; + /** + * A stream that will be validated if it can be colored. + * @default process.stdout + */ + stream?: NodeJS.WritableStream | undefined; + } /** - * Stability: 1.1 - Active development - * - * This function returns a formatted text considering the `format` passed. + * This function returns a formatted text considering the `format` passed + * for printing in a terminal. It is aware of the terminal's capabilities + * and acts according to the configuration set via `NO_COLOR`, + * `NODE_DISABLE_COLORS` and `FORCE_COLOR` environment variables. * * ```js * import { styleText } from 'node:util'; - * const errorMessage = styleText('red', 'Error! Error!'); - * console.log(errorMessage); + * import { stderr } from 'node:process'; + * + * const successMessage = styleText('green', 'Success!'); + * console.log(successMessage); + * + * const errorMessage = styleText( + * 'red', + * 'Error! Error!', + * // Validate if process.stderr has TTY + * { stream: stderr }, + * ); + * console.error(errorMessage); * ``` * - * `util.inspect.colors` also provides text formats such as `italic`, and `underline` and you can combine both: + * `util.inspect.colors` also provides text formats such as `italic`, and + * `underline` and you can combine both: * * ```js * console.log( @@ -1260,8 +1509,8 @@ declare module "util" { * ); * ``` * - * When passing an array of formats, the order of the format applied is left to right so the following style - * might overwrite the previous one. + * When passing an array of formats, the order of the format applied + * is left to right so the following style might overwrite the previous one. * * ```js * console.log( @@ -1269,6 +1518,8 @@ declare module "util" { * ); * ``` * + * The special format value `none` applies no additional styling to the text. + * * The full list of formats can be found in [modifiers](https://nodejs.org/docs/latest-v22.x/api/util.html#modifiers). * @param format A text format or an Array of text formats defined in `util.inspect.colors`. * @param text The text to to be formatted. @@ -1281,6 +1532,7 @@ declare module "util" { | Modifiers | Array, text: string, + options?: StyleTextOptions, ): string; /** * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextDecoder` API. @@ -1434,11 +1686,17 @@ declare module "util" { * @return The parsed command line arguments: */ export function parseArgs(config?: T): ParsedResults; - interface ParseArgsOptionConfig { + + /** + * Type of argument used in {@link parseArgs}. + */ + export type ParseArgsOptionsType = "boolean" | "string"; + + export interface ParseArgsOptionDescriptor { /** * Type of argument. */ - type: "string" | "boolean"; + type: ParseArgsOptionsType; /** * Whether this option can be provided multiple times. * If `true`, all values will be collected in an array. @@ -1451,15 +1709,16 @@ declare module "util" { */ short?: string | undefined; /** - * The default option value when it is not set by args. - * It must be of the same type as the the `type` property. - * When `multiple` is `true`, it must be an array. + * The default value to + * be used if (and only if) the option does not appear in the arguments to be + * parsed. It must be of the same type as the `type` property. When `multiple` + * is `true`, it must be an array. * @since v18.11.0 */ default?: string | boolean | string[] | boolean[] | undefined; } - interface ParseArgsOptionsConfig { - [longOption: string]: ParseArgsOptionConfig; + export interface ParseArgsOptionsConfig { + [longOption: string]: ParseArgsOptionDescriptor; } export interface ParseArgsConfig { /** @@ -1511,24 +1770,29 @@ declare module "util" { : T extends true ? IfTrue : IfFalse; - type ExtractOptionValue = IfDefaultsTrue< + type ExtractOptionValue = IfDefaultsTrue< T["strict"], O["type"] extends "string" ? string : O["type"] extends "boolean" ? boolean : string | boolean, string | boolean >; + type ApplyOptionalModifiers> = ( + & { -readonly [LongOption in keyof O]?: V[LongOption] } + & { [LongOption in keyof O as O[LongOption]["default"] extends {} ? LongOption : never]: V[LongOption] } + ) extends infer P ? { [K in keyof P]: P[K] } : never; // resolve intersection to object + type ParsedValues = & IfDefaultsTrue - & (T["options"] extends ParseArgsOptionsConfig ? { - -readonly [LongOption in keyof T["options"]]: - // when "default" is not undefined, the value will be present - | (T["options"][LongOption]["default"] extends {} ? never : undefined) - | IfDefaultsFalse< + & (T["options"] extends ParseArgsOptionsConfig ? ApplyOptionalModifiers< + T["options"], + { + [LongOption in keyof T["options"]]: IfDefaultsFalse< T["options"][LongOption]["multiple"], Array>, ExtractOptionValue >; - } + } + > : {}); type ParsedPositionals = IfDefaultsTrue< @@ -1539,7 +1803,7 @@ declare module "util" { type PreciseTokenForOptions< K extends string, - O extends ParseArgsOptionConfig, + O extends ParseArgsOptionDescriptor, > = O["type"] extends "string" ? { kind: "option"; index: number; @@ -1629,7 +1893,6 @@ declare module "util" { * components. When parsed, a `MIMEType` object is returned containing * properties for each of these components. * @since v19.1.0, v18.13.0 - * @experimental */ export class MIMEType { /** @@ -1847,6 +2110,18 @@ declare module "util/types" { * @since v10.0.0 */ function isBigInt64Array(value: unknown): value is BigInt64Array; + /** + * Returns `true` if the value is a BigInt object, e.g. created + * by `Object(BigInt(123))`. + * + * ```js + * util.types.isBigIntObject(Object(BigInt(123))); // Returns true + * util.types.isBigIntObject(BigInt(123)); // Returns false + * util.types.isBigIntObject(123); // Returns false + * ``` + * @since v10.4.0 + */ + function isBigIntObject(object: unknown): object is BigInt; /** * Returns `true` if the value is a `BigUint64Array` instance. * @@ -1916,7 +2191,9 @@ declare module "util/types" { * A native `External` value is a special type of object that contains a * raw C++ pointer (`void*`) for access from native code, and has no other * properties. Such objects are created either by Node.js internals or native - * addons. In JavaScript, they are [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) objects with a`null` prototype. + * addons. In JavaScript, they are + * [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) objects with a + * `null` prototype. * * ```c * #include @@ -1924,7 +2201,7 @@ declare module "util/types" { * napi_value result; * static napi_value MyNapi(napi_env env, napi_callback_info info) { * int* raw = (int*) malloc(1024); - * napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result); + * napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result); * if (status != napi_ok) { * napi_throw_error(env, NULL, "napi_create_external failed"); * return NULL; @@ -1937,17 +2214,33 @@ declare module "util/types" { * ``` * * ```js - * const native = require('napi_addon.node'); + * import native from 'napi_addon.node'; + * import { types } from 'node:util'; + * * const data = native.myNapi(); - * util.types.isExternal(data); // returns true - * util.types.isExternal(0); // returns false - * util.types.isExternal(new String('foo')); // returns false + * types.isExternal(data); // returns true + * types.isExternal(0); // returns false + * types.isExternal(new String('foo')); // returns false * ``` * - * For further information on `napi_create_external`, refer to `napi_create_external()`. + * For further information on `napi_create_external`, refer to + * [`napi_create_external()`](https://nodejs.org/docs/latest-v22.x/api/n-api.html#napi_create_external). * @since v10.0.0 */ function isExternal(object: unknown): boolean; + /** + * Returns `true` if the value is a built-in `Float16Array` instance. + * + * ```js + * util.types.isFloat16Array(new ArrayBuffer()); // Returns false + * util.types.isFloat16Array(new Float16Array()); // Returns true + * util.types.isFloat16Array(new Float32Array()); // Returns false + * ``` + * @since v22.16.0 + */ + // This does NOT return a type predicate in v22.x. + // The Float16Array feature does not yet exist in this version of Node.js. + function isFloat16Array(object: unknown): boolean; /** * Returns `true` if the value is a built-in [`Float32Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array) instance. * @@ -2068,7 +2361,8 @@ declare module "util/types" { */ function isModuleNamespaceObject(value: unknown): boolean; /** - * Returns `true` if the value was returned by the constructor of a [built-in `Error` type](https://tc39.es/ecma262/#sec-error-objects). + * Returns `true` if the value was returned by the constructor of a + * [built-in `Error` type](https://tc39.es/ecma262/#sec-error-objects). * * ```js * console.log(util.types.isNativeError(new Error())); // true @@ -2083,14 +2377,18 @@ declare module "util/types" { * console.log(util.types.isNativeError(new MyError())); // true * ``` * - * A value being `instanceof` a native error class is not equivalent to `isNativeError()` returning `true` for that value. `isNativeError()` returns `true` for errors - * which come from a different [realm](https://tc39.es/ecma262/#realm) while `instanceof Error` returns `false` for these errors: + * A value being `instanceof` a native error class is not equivalent to `isNativeError()` + * returning `true` for that value. `isNativeError()` returns `true` for errors + * which come from a different [realm](https://tc39.es/ecma262/#realm) while `instanceof Error` returns `false` + * for these errors: * * ```js - * import vm from 'node:vm'; - * const context = vm.createContext({}); - * const myError = vm.runInContext('new Error()', context); - * console.log(util.types.isNativeError(myError)); // true + * import { createContext, runInContext } from 'node:vm'; + * import { types } from 'node:util'; + * + * const context = createContext({}); + * const myError = runInContext('new Error()', context); + * console.log(types.isNativeError(myError)); // true * console.log(myError instanceof Error); // false * ``` * diff --git a/node_modules/@types/node/v8.d.ts b/node_modules/@types/node/v8.d.ts index 040bcfafa..8f7106e77 100644 --- a/node_modules/@types/node/v8.d.ts +++ b/node_modules/@types/node/v8.d.ts @@ -113,6 +113,87 @@ declare module "v8" { * @since v1.0.0 */ function getHeapStatistics(): HeapInfo; + /** + * It returns an object with a structure similar to the + * [`cppgc::HeapStatistics`](https://v8docs.nodesource.com/node-22.4/d7/d51/heap-statistics_8h_source.html) + * object. See the [V8 documentation](https://v8docs.nodesource.com/node-22.4/df/d2f/structcppgc_1_1_heap_statistics.html) + * for more information about the properties of the object. + * + * ```js + * // Detailed + * ({ + * committed_size_bytes: 131072, + * resident_size_bytes: 131072, + * used_size_bytes: 152, + * space_statistics: [ + * { + * name: 'NormalPageSpace0', + * committed_size_bytes: 0, + * resident_size_bytes: 0, + * used_size_bytes: 0, + * page_stats: [{}], + * free_list_stats: {}, + * }, + * { + * name: 'NormalPageSpace1', + * committed_size_bytes: 131072, + * resident_size_bytes: 131072, + * used_size_bytes: 152, + * page_stats: [{}], + * free_list_stats: {}, + * }, + * { + * name: 'NormalPageSpace2', + * committed_size_bytes: 0, + * resident_size_bytes: 0, + * used_size_bytes: 0, + * page_stats: [{}], + * free_list_stats: {}, + * }, + * { + * name: 'NormalPageSpace3', + * committed_size_bytes: 0, + * resident_size_bytes: 0, + * used_size_bytes: 0, + * page_stats: [{}], + * free_list_stats: {}, + * }, + * { + * name: 'LargePageSpace', + * committed_size_bytes: 0, + * resident_size_bytes: 0, + * used_size_bytes: 0, + * page_stats: [{}], + * free_list_stats: {}, + * }, + * ], + * type_names: [], + * detail_level: 'detailed', + * }); + * ``` + * + * ```js + * // Brief + * ({ + * committed_size_bytes: 131072, + * resident_size_bytes: 131072, + * used_size_bytes: 128864, + * space_statistics: [], + * type_names: [], + * detail_level: 'brief', + * }); + * ``` + * @since v22.15.0 + * @param detailLevel **Default:** `'detailed'`. Specifies the level of detail in the returned statistics. + * Accepted values are: + * * `'brief'`: Brief statistics contain only the top-level + * allocated and used + * memory statistics for the entire heap. + * * `'detailed'`: Detailed statistics also contain a break + * down per space and page, as well as freelist statistics + * and object type histograms. + */ + function getCppHeapStatistics(detailLevel?: "brief" | "detailed"): object; /** * Returns statistics about the V8 heap spaces, i.e. the segments which make up * the V8 heap. Neither the ordering of heap spaces, nor the availability of a @@ -319,6 +400,39 @@ declare module "v8" { * @since v12.8.0 */ function getHeapCodeStatistics(): HeapCodeStatistics; + /** + * V8 only supports `Latin-1/ISO-8859-1` and `UTF16` as the underlying representation of a string. + * If the `content` uses `Latin-1/ISO-8859-1` as the underlying representation, this function will return true; + * otherwise, it returns false. + * + * If this method returns false, that does not mean that the string contains some characters not in `Latin-1/ISO-8859-1`. + * Sometimes a `Latin-1` string may also be represented as `UTF16`. + * + * ```js + * const { isStringOneByteRepresentation } = require('node:v8'); + * + * const Encoding = { + * latin1: 1, + * utf16le: 2, + * }; + * const buffer = Buffer.alloc(100); + * function writeString(input) { + * if (isStringOneByteRepresentation(input)) { + * buffer.writeUint8(Encoding.latin1); + * buffer.writeUint32LE(input.length, 1); + * buffer.write(input, 5, 'latin1'); + * } else { + * buffer.writeUint8(Encoding.utf16le); + * buffer.writeUint32LE(input.length * 2, 1); + * buffer.write(input, 5, 'utf16le'); + * } + * } + * writeString('hello'); + * writeString('你好'); + * ``` + * @since v22.15.0 + */ + function isStringOneByteRepresentation(content: string): boolean; /** * @since v8.0.0 */ @@ -445,7 +559,7 @@ declare module "v8" { * @since v8.0.0 * @param buffer A buffer returned by {@link serialize}. */ - function deserialize(buffer: NodeJS.TypedArray): any; + function deserialize(buffer: NodeJS.ArrayBufferView): any; /** * The `v8.takeCoverage()` method allows the user to write the coverage started by `NODE_V8_COVERAGE` to disk on demand. This method can be invoked multiple * times during the lifetime of the process. Each time the execution counter will @@ -467,7 +581,6 @@ declare module "v8" { /** * The API is a no-op if `--heapsnapshot-near-heap-limit` is already set from the command line or the API is called more than once. * `limit` must be a positive integer. See [`--heapsnapshot-near-heap-limit`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--heapsnapshot-near-heap-limitmax_count) for more information. - * @experimental * @since v18.10.0, v16.18.0 */ function setHeapSnapshotNearHeapLimit(limit: number): void; @@ -693,33 +806,6 @@ declare module "v8" { */ const promiseHooks: PromiseHooks; type StartupSnapshotCallbackFn = (args: any) => any; - interface StartupSnapshot { - /** - * Add a callback that will be called when the Node.js instance is about to get serialized into a snapshot and exit. - * This can be used to release resources that should not or cannot be serialized or to convert user data into a form more suitable for serialization. - * @since v18.6.0, v16.17.0 - */ - addSerializeCallback(callback: StartupSnapshotCallbackFn, data?: any): void; - /** - * Add a callback that will be called when the Node.js instance is deserialized from a snapshot. - * The `callback` and the `data` (if provided) will be serialized into the snapshot, they can be used to re-initialize the state of the application or - * to re-acquire resources that the application needs when the application is restarted from the snapshot. - * @since v18.6.0, v16.17.0 - */ - addDeserializeCallback(callback: StartupSnapshotCallbackFn, data?: any): void; - /** - * This sets the entry point of the Node.js application when it is deserialized from a snapshot. This can be called only once in the snapshot building script. - * If called, the deserialized application no longer needs an additional entry point script to start up and will simply invoke the callback along with the deserialized - * data (if provided), otherwise an entry point script still needs to be provided to the deserialized application. - * @since v18.6.0, v16.17.0 - */ - setDeserializeMainFunction(callback: StartupSnapshotCallbackFn, data?: any): void; - /** - * Returns true if the Node.js instance is run to build a snapshot. - * @since v18.6.0, v16.17.0 - */ - isBuildingSnapshot(): boolean; - } /** * The `v8.startupSnapshot` interface can be used to add serialization and deserialization hooks for custom startup snapshots. * @@ -798,10 +884,35 @@ declare module "v8" { * * Currently the application deserialized from a user-land snapshot cannot be snapshotted again, so these APIs are only available to applications that are not deserialized from a user-land snapshot. * - * @experimental * @since v18.6.0, v16.17.0 */ - const startupSnapshot: StartupSnapshot; + namespace startupSnapshot { + /** + * Add a callback that will be called when the Node.js instance is about to get serialized into a snapshot and exit. + * This can be used to release resources that should not or cannot be serialized or to convert user data into a form more suitable for serialization. + * @since v18.6.0, v16.17.0 + */ + function addSerializeCallback(callback: StartupSnapshotCallbackFn, data?: any): void; + /** + * Add a callback that will be called when the Node.js instance is deserialized from a snapshot. + * The `callback` and the `data` (if provided) will be serialized into the snapshot, they can be used to re-initialize the state of the application or + * to re-acquire resources that the application needs when the application is restarted from the snapshot. + * @since v18.6.0, v16.17.0 + */ + function addDeserializeCallback(callback: StartupSnapshotCallbackFn, data?: any): void; + /** + * This sets the entry point of the Node.js application when it is deserialized from a snapshot. This can be called only once in the snapshot building script. + * If called, the deserialized application no longer needs an additional entry point script to start up and will simply invoke the callback along with the deserialized + * data (if provided), otherwise an entry point script still needs to be provided to the deserialized application. + * @since v18.6.0, v16.17.0 + */ + function setDeserializeMainFunction(callback: StartupSnapshotCallbackFn, data?: any): void; + /** + * Returns true if the Node.js instance is run to build a snapshot. + * @since v18.6.0, v16.17.0 + */ + function isBuildingSnapshot(): boolean; + } } declare module "node:v8" { export * from "v8"; diff --git a/node_modules/@types/node/vm.d.ts b/node_modules/@types/node/vm.d.ts index 9d9ff1ac6..02cebcec0 100644 --- a/node_modules/@types/node/vm.d.ts +++ b/node_modules/@types/node/vm.d.ts @@ -56,9 +56,14 @@ declare module "vm" { */ columnOffset?: number | undefined; } + type DynamicModuleLoader = ( + specifier: string, + referrer: T, + importAttributes: ImportAttributes, + ) => Module | Promise; interface ScriptOptions extends BaseOptions { /** - * V8's code cache data for the supplied source. + * Provides an optional data with V8's code cache data for the supplied source. */ cachedData?: Buffer | NodeJS.ArrayBufferView | undefined; /** @deprecated in favor of `script.createCachedData()` */ @@ -69,7 +74,7 @@ declare module "vm" { * [Support of dynamic `import()` in compilation APIs](https://nodejs.org/docs/latest-v22.x/api/vm.html#support-of-dynamic-import-in-compilation-apis). */ importModuleDynamically?: - | ((specifier: string, script: Script, importAttributes: ImportAttributes) => Module) + | DynamicModuleLoader