Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 2efce0f

Browse filesBrowse files
anonrigruyadorno
anonrig
authored and
ruyadorno
committed
typings: add JSDoc for internal/validators
PR-URL: #44181 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com>
1 parent 19557ad commit 2efce0f
Copy full SHA for 2efce0f

File tree

Expand file treeCollapse file tree

2 files changed

+153
-7
lines changed
Open diff view settings
Filter options
Expand file treeCollapse file tree

2 files changed

+153
-7
lines changed
Open diff view settings
Collapse file

‎lib/internal/errors.js‎

Copy file name to clipboardExpand all lines: lib/internal/errors.js
+3-2Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -392,8 +392,9 @@ function makeNodeErrorWithCode(Base, key) {
392392

393393
/**
394394
* This function removes unnecessary frames from Node.js core errors.
395-
* @template {(...args: any[]) => any} T
396-
* @type {(fn: T) => T}
395+
* @template {(...args: unknown[]) => unknown} T
396+
* @param {T} fn
397+
* @returns {T}
397398
*/
398399
function hideStackFrames(fn) {
399400
// We rename the functions that will be hidden to cut off the stacktrace
Collapse file

‎lib/internal/validators.js‎

Copy file name to clipboardExpand all lines: lib/internal/validators.js
+150-5Lines changed: 150 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,18 @@ const {
3434
} = require('internal/util/types');
3535
const { signals } = internalBinding('constants').os;
3636

37+
/**
38+
* @param {*} value
39+
* @returns {boolean}
40+
*/
3741
function isInt32(value) {
3842
return value === (value | 0);
3943
}
4044

45+
/**
46+
* @param {*} value
47+
* @returns {boolean}
48+
*/
4149
function isUint32(value) {
4250
return value === (value >>> 0);
4351
}
@@ -70,6 +78,16 @@ function parseFileMode(value, name, def) {
7078
return value;
7179
}
7280

81+
/**
82+
* @callback validateInteger
83+
* @param {*} value
84+
* @param {string} name
85+
* @param {number} [min]
86+
* @param {number} [max]
87+
* @returns {asserts value is number}
88+
*/
89+
90+
/** @type {validateInteger} */
7391
const validateInteger = hideStackFrames(
7492
(value, name, min = NumberMIN_SAFE_INTEGER, max = NumberMAX_SAFE_INTEGER) => {
7593
if (typeof value !== 'number')
@@ -81,6 +99,16 @@ const validateInteger = hideStackFrames(
8199
}
82100
);
83101

102+
/**
103+
* @callback validateInt32
104+
* @param {*} value
105+
* @param {string} name
106+
* @param {number} [min]
107+
* @param {number} [max]
108+
* @returns {asserts value is number}
109+
*/
110+
111+
/** @type {validateInt32} */
84112
const validateInt32 = hideStackFrames(
85113
(value, name, min = -2147483648, max = 2147483647) => {
86114
// The defaults for min and max correspond to the limits of 32-bit integers.
@@ -96,7 +124,16 @@ const validateInt32 = hideStackFrames(
96124
}
97125
);
98126

99-
const validateUint32 = hideStackFrames((value, name, positive) => {
127+
/**
128+
* @callback validateUint32
129+
* @param {*} value
130+
* @param {string} name
131+
* @param {number|boolean} [positive=false]
132+
* @returns {asserts value is number}
133+
*/
134+
135+
/** @type {validateUint32} */
136+
const validateUint32 = hideStackFrames((value, name, positive = false) => {
100137
if (typeof value !== 'number') {
101138
throw new ERR_INVALID_ARG_TYPE(name, 'number', value);
102139
}
@@ -111,11 +148,29 @@ const validateUint32 = hideStackFrames((value, name, positive) => {
111148
}
112149
});
113150

151+
/**
152+
* @callback validateString
153+
* @param {*} value
154+
* @param {string} name
155+
* @returns {asserts value is string}
156+
*/
157+
158+
/** @type {validateString} */
114159
function validateString(value, name) {
115160
if (typeof value !== 'string')
116161
throw new ERR_INVALID_ARG_TYPE(name, 'string', value);
117162
}
118163

164+
/**
165+
* @callback validateNumber
166+
* @param {*} value
167+
* @param {string} name
168+
* @param {number} [min]
169+
* @param {number} [max]
170+
* @returns {asserts value is number}
171+
*/
172+
173+
/** @type {validateNumber} */
119174
function validateNumber(value, name, min = undefined, max) {
120175
if (typeof value !== 'number')
121176
throw new ERR_INVALID_ARG_TYPE(name, 'number', value);
@@ -129,6 +184,15 @@ function validateNumber(value, name, min = undefined, max) {
129184
}
130185
}
131186

187+
/**
188+
* @callback validateOneOf
189+
* @template T
190+
* @param {T} value
191+
* @param {string} name
192+
* @param {T[]} oneOf
193+
*/
194+
195+
/** @type {validateOneOf} */
132196
const validateOneOf = hideStackFrames((value, name, oneOf) => {
133197
if (!ArrayPrototypeIncludes(oneOf, value)) {
134198
const allowed = ArrayPrototypeJoin(
@@ -140,6 +204,14 @@ const validateOneOf = hideStackFrames((value, name, oneOf) => {
140204
}
141205
});
142206

207+
/**
208+
* @callback validateBoolean
209+
* @param {*} value
210+
* @param {string} name
211+
* @returns {asserts value is boolean}
212+
*/
213+
214+
/** @type {validateBoolean} */
143215
function validateBoolean(value, name) {
144216
if (typeof value !== 'boolean')
145217
throw new ERR_INVALID_ARG_TYPE(name, 'boolean', value);
@@ -152,16 +224,19 @@ function getOwnPropertyValueOrDefault(options, key, defaultValue) {
152224
}
153225

154226
/**
155-
* @param {unknown} value
227+
* @callback validateObject
228+
* @param {*} value
156229
* @param {string} name
157230
* @param {{
158231
* allowArray?: boolean,
159232
* allowFunction?: boolean,
160233
* nullable?: boolean
161234
* }} [options]
162235
*/
236+
237+
/** @type {validateObject} */
163238
const validateObject = hideStackFrames(
164-
(value, name, options) => {
239+
(value, name, options = null) => {
165240
const allowArray = getOwnPropertyValueOrDefault(options, 'allowArray', false);
166241
const allowFunction = getOwnPropertyValueOrDefault(options, 'allowFunction', false);
167242
const nullable = getOwnPropertyValueOrDefault(options, 'nullable', false);
@@ -174,6 +249,15 @@ const validateObject = hideStackFrames(
174249
}
175250
});
176251

252+
/**
253+
* @callback validateArray
254+
* @param {*} value
255+
* @param {string} name
256+
* @param {number} [minLength]
257+
* @returns {asserts value is any[]}
258+
*/
259+
260+
/** @type {validateArray} */
177261
const validateArray = hideStackFrames((value, name, minLength = 0) => {
178262
if (!ArrayIsArray(value)) {
179263
throw new ERR_INVALID_ARG_TYPE(name, 'Array', value);
@@ -184,6 +268,12 @@ const validateArray = hideStackFrames((value, name, minLength = 0) => {
184268
}
185269
});
186270

271+
// eslint-disable-next-line jsdoc/require-returns-check
272+
/**
273+
* @param {*} signal
274+
* @param {string} [name='signal']
275+
* @returns {asserts signal is keyof signals}
276+
*/
187277
function validateSignalName(signal, name = 'signal') {
188278
validateString(signal, name);
189279

@@ -197,6 +287,14 @@ function validateSignalName(signal, name = 'signal') {
197287
}
198288
}
199289

290+
/**
291+
* @callback validateBuffer
292+
* @param {*} buffer
293+
* @param {string} [name='buffer']
294+
* @returns {asserts buffer is ArrayBufferView}
295+
*/
296+
297+
/** @type {validateBuffer} */
200298
const validateBuffer = hideStackFrames((buffer, name = 'buffer') => {
201299
if (!isArrayBufferView(buffer)) {
202300
throw new ERR_INVALID_ARG_TYPE(name,
@@ -205,6 +303,10 @@ const validateBuffer = hideStackFrames((buffer, name = 'buffer') => {
205303
}
206304
});
207305

306+
/**
307+
* @param {string} data
308+
* @param {string} encoding
309+
*/
208310
function validateEncoding(data, encoding) {
209311
const normalizedEncoding = normalizeEncoding(encoding);
210312
const length = data.length;
@@ -215,8 +317,14 @@ function validateEncoding(data, encoding) {
215317
}
216318
}
217319

218-
// Check that the port number is not NaN when coerced to a number,
219-
// is an integer and that it falls within the legal range of port numbers.
320+
/**
321+
* Check that the port number is not NaN when coerced to a number,
322+
* is an integer and that it falls within the legal range of port numbers.
323+
* @param {*} port
324+
* @param {string} [name='Port']
325+
* @param {boolean} [allowZero=true]
326+
* @returns {number}
327+
*/
220328
function validatePort(port, name = 'Port', allowZero = true) {
221329
if ((typeof port !== 'number' && typeof port !== 'string') ||
222330
(typeof port === 'string' && StringPrototypeTrim(port).length === 0) ||
@@ -228,6 +336,13 @@ function validatePort(port, name = 'Port', allowZero = true) {
228336
return port | 0;
229337
}
230338

339+
/**
340+
* @callback validateAbortSignal
341+
* @param {*} signal
342+
* @param {string} name
343+
*/
344+
345+
/** @type {validateAbortSignal} */
231346
const validateAbortSignal = hideStackFrames((signal, name) => {
232347
if (signal !== undefined &&
233348
(signal === null ||
@@ -237,21 +352,51 @@ const validateAbortSignal = hideStackFrames((signal, name) => {
237352
}
238353
});
239354

355+
/**
356+
* @callback validateFunction
357+
* @param {*} value
358+
* @param {string} name
359+
* @returns {asserts value is Function}
360+
*/
361+
362+
/** @type {validateFunction} */
240363
const validateFunction = hideStackFrames((value, name) => {
241364
if (typeof value !== 'function')
242365
throw new ERR_INVALID_ARG_TYPE(name, 'Function', value);
243366
});
244367

368+
/**
369+
* @callback validatePlainFunction
370+
* @param {*} value
371+
* @param {string} name
372+
* @returns {asserts value is Function}
373+
*/
374+
375+
/** @type {validatePlainFunction} */
245376
const validatePlainFunction = hideStackFrames((value, name) => {
246377
if (typeof value !== 'function' || isAsyncFunction(value))
247378
throw new ERR_INVALID_ARG_TYPE(name, 'Function', value);
248379
});
249380

381+
/**
382+
* @callback validateUndefined
383+
* @param {*} value
384+
* @param {string} name
385+
* @returns {asserts value is undefined}
386+
*/
387+
388+
/** @type {validateUndefined} */
250389
const validateUndefined = hideStackFrames((value, name) => {
251390
if (value !== undefined)
252391
throw new ERR_INVALID_ARG_TYPE(name, 'undefined', value);
253392
});
254393

394+
/**
395+
* @template T
396+
* @param {T} value
397+
* @param {string} name
398+
* @param {T[]} union
399+
*/
255400
function validateUnion(value, name, union) {
256401
if (!ArrayPrototypeIncludes(union, value)) {
257402
throw new ERR_INVALID_ARG_TYPE(name, `('${ArrayPrototypeJoin(union, '|')}')`, value);

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.