Skip to content

Commit 2efce0f

Browse 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

2 files changed

Lines changed: 153 additions & 7 deletions

File tree

‎lib/internal/errors.js‎

Lines 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
functionhideStackFrames(fn){
399400
// We rename the functions that will be hidden to cut off the stacktrace

‎lib/internal/validators.js‎

Lines 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
functionisInt32(value){
3842
returnvalue===(value|0);
3943
}
4044

45+
/**
46+
* @param {*} value
47+
* @returns {boolean}
48+
*/
4149
functionisUint32(value){
4250
returnvalue===(value>>>0);
4351
}
@@ -70,6 +78,16 @@ function parseFileMode(value, name, def) {
7078
returnvalue;
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
constvalidateInteger=hideStackFrames(
7492
(value,name,min=NumberMIN_SAFE_INTEGER,max=NumberMAX_SAFE_INTEGER)=>{
7593
if(typeofvalue!=='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
constvalidateInt32=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-
constvalidateUint32=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+
constvalidateUint32=hideStackFrames((value,name,positive=false)=>{
100137
if(typeofvalue!=='number'){
101138
thrownewERR_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
functionvalidateString(value,name){
115160
if(typeofvalue!=='string')
116161
thrownewERR_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
functionvalidateNumber(value,name,min=undefined,max){
120175
if(typeofvalue!=='number')
121176
thrownewERR_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
constvalidateOneOf=hideStackFrames((value,name,oneOf)=>{
133197
if(!ArrayPrototypeIncludes(oneOf,value)){
134198
constallowed=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
functionvalidateBoolean(value,name){
144216
if(typeofvalue!=='boolean')
145217
thrownewERR_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
constvalidateObject=hideStackFrames(
164-
(value,name,options)=>{
239+
(value,name,options=null)=>{
165240
constallowArray=getOwnPropertyValueOrDefault(options,'allowArray',false);
166241
constallowFunction=getOwnPropertyValueOrDefault(options,'allowFunction',false);
167242
constnullable=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
constvalidateArray=hideStackFrames((value,name,minLength=0)=>{
178262
if(!ArrayIsArray(value)){
179263
thrownewERR_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
functionvalidateSignalName(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
constvalidateBuffer=hideStackFrames((buffer,name='buffer')=>{
201299
if(!isArrayBufferView(buffer)){
202300
thrownewERR_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
functionvalidateEncoding(data,encoding){
209311
constnormalizedEncoding=normalizeEncoding(encoding);
210312
constlength=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
functionvalidatePort(port,name='Port',allowZero=true){
221329
if((typeofport!=='number'&&typeofport!=='string')||
222330
(typeofport==='string'&&StringPrototypeTrim(port).length===0)||
@@ -228,6 +336,13 @@ function validatePort(port, name = 'Port', allowZero = true) {
228336
returnport|0;
229337
}
230338

339+
/**
340+
* @callback validateAbortSignal
341+
* @param {*} signal
342+
* @param {string} name
343+
*/
344+
345+
/** @type {validateAbortSignal} */
231346
constvalidateAbortSignal=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
constvalidateFunction=hideStackFrames((value,name)=>{
241364
if(typeofvalue!=='function')
242365
thrownewERR_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
constvalidatePlainFunction=hideStackFrames((value,name)=>{
246377
if(typeofvalue!=='function'||isAsyncFunction(value))
247378
thrownewERR_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
constvalidateUndefined=hideStackFrames((value,name)=>{
251390
if(value!==undefined)
252391
thrownewERR_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
functionvalidateUnion(value,name,union){
256401
if(!ArrayPrototypeIncludes(union,value)){
257402
thrownewERR_INVALID_ARG_TYPE(name,`('${ArrayPrototypeJoin(union,'|')}')`,value);

0 commit comments

Comments
 (0)