fix: fix 100s of (mostly) JSDoc issues found by TypeScript (#2514)

packages/fns/src/asyncCompose.js

@@ -2,10 +2,18 @@
 
 import reverse from './reverse';
 
+/**
+ * @typedef {Function} AsyncCompose
+ * @param {any} value
+ * @param {...any} args
+ * @returns {any} result
+ */
+
 /**
  * Performs right-to-left function composition with async functions support
  *
- * @param  {...any} functions
+ * @param {...Function} fns functions
+ * @returns {AsyncCompose} composed function
  */
 const asyncCompose = (...fns) => async (value, ...args) => {
   let result = value;

packages/fns/src/capitalize.js

@@ -1,12 +1,12 @@
 /**
  * Capitalize first letter of each word
  *
- * @param {String} string
- * @returns {String} capitalized string
+ * @param {string} value string
+ * @returns {string} capitalized string
  */
-const capitalize = value => {
+const capitalize = (value) => {
   if (!value) return value;
-  return value.replace(/(^|\s)\S/g, l => l.toUpperCase());
+  return value.replace(/(^|\s)\S/g, (l) => l.toUpperCase());
 };
 
 export default capitalize;

packages/fns/src/castArray.js

@@ -1,8 +1,9 @@
 /**
  * Casts value to array
  *
- * @param {any} value
- * @returns {Array} casted value
+ * @template T
+ * @param {T|T[]} value value
+ * @returns {T[]} array
  */
 const castArray = value => {
   return Array.isArray(value) ? value : [value];

packages/fns/src/compose.js

@@ -2,10 +2,18 @@
 
 import reverse from './reverse';
 
+/**
+ * @typedef {Function} Compose
+ * @param {any} value
+ * @param {...any} args
+ * @returns {any} result
+ */
+
 /**
  * Performs right-to-left function composition
  *
- * @param  {...any} functions
+ * @param {...Function} fns functions
+ * @returns {Compose} composed function
  */
 const compose = (...fns) => (value, ...args) => {
   let result = value;

packages/fns/src/matchPercent.js

@@ -1,16 +1,20 @@
-const isPercent = value => /((-)?\d+\.?\d*)%/g.exec(value);
+/**
+ * @param {string | number} value
+ * @returns {RegExpExecArray | null} match
+ */
+const isPercent = value => /((-)?\d+\.?\d*)%/g.exec(`${value}`);
 
 /**
  * Get percentage value of input
  *
- * @param {String} value
- * @returns {Object} percent value (if matches)
+ * @param {string | number} value
+ * @returns {{ percent: number, value: number } | null} percent value (if matches)
  */
 const matchPercent = value => {
   const match = isPercent(value);
 
   if (match) {
-    const f = parseFloat(match[1], 10);
+    const f = parseFloat(match[1]);
     const percent = f / 100;
 
     return { percent, value: f };

packages/fns/src/upperFirst.js

@@ -1,10 +1,10 @@
 /**
  * Capitalize first letter of string
  *
- * @param {String} string
- * @returns {String} capitalized string
+ * @param {string} value string
+ * @returns {string} capitalized string
  */
-const upperFirst = value => {
+const upperFirst = (value) => {
   if (!value) return value;
   return value.charAt(0).toUpperCase() + value.slice(1);
 };

packages/layout/src/canvas/measureCanvas.js

@@ -6,7 +6,7 @@ import isHeightAuto from '../page/isHeightAuto';
 
 const SAFETY_HEIGHT = 10;
 
-const getMax = values => Math.max(-Infinity, ...values);
+const getMax = (values) => Math.max(-Infinity, ...values);
 
 /**
  * Helper object to predict canvas size
@@ -88,22 +88,23 @@ const measureCtx = () => {
   ctx.linearGradient = nil;
   ctx.radialGradient = nil;
 
-  ctx.getWidth = () => getMax(points.map(p => p[0]));
-  ctx.getHeight = () => getMax(points.map(p => p[1]));
+  ctx.getWidth = () => getMax(points.map((p) => p[0]));
+  ctx.getHeight = () => getMax(points.map((p) => p[1]));
 
   return ctx;
 };
 
+/**
+ * @typedef {Function} MeasureCanvas
+ * @returns {{ width: number, height: number }} canvas width and height
+ */
+
 /**
  * Yoga canvas measure function
  *
  * @param {Object} page
  * @param {Object} node
- * @param {Number} width
- * @param {Number} widthMode
- * @param {Number} height
- * @param {Number} heightMode
- * @returns {Object} canvas width and height
+ * @returns {MeasureCanvas} measure canvas
  */
 const measureCanvas = (page, node) => () => {
   const imageMargin = getMargin(node);
@@ -124,7 +125,7 @@ const measureCanvas = (page, node) => () => {
   const width = ctx.getWidth();
   const height = Math.min(pageArea, ctx.getHeight());
 
-  return { height, width };
+  return { width, height };
 };
 
 export default measureCanvas;

packages/layout/src/image/getRatio.js

@@ -1,10 +1,10 @@
 /**
  * Get image ratio
  *
- * @param {Object} image node
- * @returns {Number} image ratio
+ * @param {Object} node image node
+ * @returns {number} image ratio
  */
-const getRatio = node => {
+const getRatio = (node) => {
   return node.image?.data ? node.image.width / node.image.height : 1;
 };
 

packages/layout/src/image/getSource.js

@@ -1,10 +1,10 @@
 /**
  * Get image source
  *
- * @param {Object} image node
- * @returns {String | Object} image src
+ * @param {Object} node image node
+ * @returns {string | Object} image src
  */
-const getSource = node =>
+const getSource = (node) =>
   node.props?.src || node.props?.source || node.props?.href;
 
 export default getSource;

packages/layout/src/image/measureImage.js

@@ -7,16 +7,21 @@ import isHeightAuto from '../page/isHeightAuto';
 
 const SAFETY_HEIGHT = 10;
 
+/**
+ * @typedef {Function} MeasureImage
+ * @param {number} width
+ * @param {number} widthMode
+ * @param {number} height
+ * @param {number} heightMode
+ * @returns {{ width: number, height: number }} image width and height
+ */
+
 /**
  * Yoga image measure function
  *
- * @param {Object} page
- * @param {Object} node
- * @param {Number} width
- * @param {Number} widthMode
- * @param {Number} height
- * @param {Number} heightMode
- * @returns {Object} image width and height
+ * @param {Object} page page
+ * @param {Object} node node
+ * @returns {MeasureImage} measure image
  */
 const measureImage = (page, node) => (width, widthMode, height, heightMode) => {
   const imageRatio = getRatio(node);

packages/layout/src/image/resolveSource.js

@@ -4,7 +4,7 @@
  * Also it handles factories and async sources.
  *
  * @param {string | Object | Function} src
- * @returns {object} resolved src
+ * @returns {Promise<Object>} resolved src
  */
 const resolveSource = async src => {
   const source = typeof src === 'function' ? await src() : await src;

packages/layout/src/node/createInstances.js

@@ -1,22 +1,22 @@
 import { castArray } from '@react-pdf/fns';
 import { TextInstance } from '@react-pdf/primitives';
 
-const isString = value => typeof value === 'string';
+const isString = (value) => typeof value === 'string';
 
-const isNumber = value => typeof value === 'number';
+const isNumber = (value) => typeof value === 'number';
 
-const isFragment = value =>
+const isFragment = (value) =>
   value && value.type === Symbol.for('react.fragment');
 
 /**
  * Transforms a react element instance to internal element format.
  *
  * Can return multiple instances in the case of arrays or fragments.
  *
- * @param {Object} React element
- * @returns {Array} parsed react elements
+ * @param {Object} element React element
+ * @returns {Object[]} parsed React elements
  */
-const createInstances = element => {
+const createInstances = (element) => {
   if (!element) return [];
 
   if (isString(element) || isNumber(element)) {

packages/layout/src/node/getBorderWidth.js

@@ -7,9 +7,9 @@ const getComputedBorder = (yogaNode, edge) =>
  * Get Yoga computed border width. Zero otherwise
  *
  * @param {Object} node
- * @return {Object} border widths
+ * @returns {{ borderTopWidth: number, borderRightWidth: number, borderBottomWidth: number, borderLeftWidth: number }} border widths
  */
-const getBorderWidth = node => {
+const getBorderWidth = (node) => {
   const { yogaNode } = node;
 
   return {

packages/layout/src/node/getDimension.js

@@ -7,9 +7,9 @@ const DEFAULT_DIMENSION = {
  * Get Yoga computed dimensions. Zero otherwise
  *
  * @param {Object} node
- * @return {Object} dimensions
+ * @returns {{ width: number, height: number }} dimensions
  */
-const getDimension = node => {
+const getDimension = (node) => {
   const { yogaNode } = node;
 
   if (!yogaNode) return DEFAULT_DIMENSION;

packages/layout/src/node/getMargin.js

@@ -9,9 +9,9 @@ const getComputedMargin = (node, edge) => {
  * Get Yoga computed magins. Zero otherwise
  *
  * @param {Object} node
- * @return {Object} margins
+ * @returns {{ marginTop: number, marginRight: number, marginBottom: number, marginLeft: number }} margins
  */
-const getMargin = node => {
+const getMargin = (node) => {
   const { style, box } = node;
 
   const marginTop =

packages/layout/src/node/getOrigin.js

@@ -1,15 +1,15 @@
 import { isNil, matchPercent } from '@react-pdf/fns';
 
-const getTransformStyle = s => node =>
+const getTransformStyle = (s) => (node) =>
   isNil(node.style?.[s]) ? '50%' : node.style?.[s];
 
 /**
  * Get node origin
  *
  * @param {Object} node
- * @returns {Object} node origin
+ * @returns {{ left?: number, top?: number }} node origin
  */
-const getOrigin = node => {
+const getOrigin = (node) => {
   if (!node.box) return {};
 
   const { left, top, width, height } = node.box;

packages/layout/src/node/getPadding.js

@@ -9,9 +9,9 @@ const getComputedPadding = (node, edge) => {
  * Get Yoga computed paddings. Zero otherwise
  *
  * @param {Object} node
- * @return {Object} paddings
+ * @returns {{ paddingTop: number, paddingRight: number, paddingBottom: number, paddingLeft: number }} paddings
  */
-const getPadding = node => {
+const getPadding = (node) => {
   const { style, box } = node;
 
   const paddingTop =

packages/layout/src/node/getPosition.js

@@ -2,9 +2,9 @@
  * Get Yoga computed position. Zero otherwise
  *
  * @param {Object} node
- * @return {Object} position
+ * @returns {{ top: number, right: number, bottom: number, left: number }} position
  */
-const getPosition = node => {
+const getPosition = (node) => {
   const { yogaNode } = node;
 
   return {

packages/layout/src/node/setAlign.js

@@ -11,13 +11,23 @@ const ALIGN = {
   'space-around': Yoga.ALIGN_SPACE_AROUND,
 };
 
+/**
+ * @typedef {Function} NodeInstanceWrapper
+ * @param {Object} node node instance
+ * @returns {Object} node instance
+ */
+
+/**
+ * @typedef {Function} AlignSetter
+ * @param {string} value align value
+ * @returns {NodeInstanceWrapper} node instance wrapper
+ */
+
 /**
  * Set generic align attribute to node's Yoga instance
  *
- * @param {String} specific align property
- * @param {String} align value
- * @param {Object} node instance
- * @return {Object} node instance
+ * @param {string} attr specific align property
+ * @returns {AlignSetter} align setter
  */
 const setAlign = attr => value => node => {
   const { yogaNode } = node;

packages/layout/src/node/setAlignContent.js

@@ -3,9 +3,9 @@ import setAlign from './setAlign';
 /**
  * Set align content attribute to node's Yoga instance
  *
- * @param {String} align value
+ * @param {string} align value
  * @param {Object} node instance
- * @return {Object} node instance
+ * @returns {Object} node instance
  */
 const setAlignContent = setAlign('content');
 

packages/layout/src/node/setAlignItems.js

@@ -3,9 +3,9 @@ import setAlign from './setAlign';
 /**
  * Set align items attribute to node's Yoga instance
  *
- * @param {String} align value
+ * @param {string} align value
  * @param {Object} node instance
- * @return {Object} node instance
+ * @returns {Object} node instance
  */
 const setAlignItems = setAlign('items');
 

packages/layout/src/node/setAlignSelf.js

@@ -3,9 +3,9 @@ import setAlign from './setAlign';
 /**
  * Set align self attribute to node's Yoga instance
  *
- * @param {String} align value
+ * @param {string} align value
  * @param {Object} node instance
- * @return {Object} node instance
+ * @returns {Object} node instance
  */
 const setAlignSelf = setAlign('self');