Creating JSDoc `@types` for Different Data Types in JavaScript

Readme.md

Creating JSDoc @types for Different Data Types in JavaScript

JSDoc as an alternative TypeScript syntax

• https://alexharri.com/blog/jsdoc-as-an-alternative-typescript-syntax
• https://dev.to/samuel-braun/boost-your-javascript-with-jsdoc-typing-3hb3

Primitive Types

Here's how you can do it for common primitive types:

1. String

   /**
    * @type {string}
    */
   let myString;

2. Number

   /**
    * @type {number}
    */
   let myNumber;

3. Boolean

   /**
    * @type {boolean}
    */
   let myBoolean;

4. Null

   /**
    * @type {null}
    */
   let someValue;

Union Types

You can use JSDoc @type to specify union types, allowing a variable to hold values of multiple types. Here are a few examples:

/**
 * Example 1: Union of string or boolean
 * @type {string | boolean}
 */
let sb;

/**
 * Example 2: Union of number or null
 * @type {number | null}
 */
let numOrNull;

/**
 * Example 3: Union of string, number, or boolean
 * @type {string | number | boolean}
 */
let strNumBool;

/**
 * Example 4: Union of string, number, or null
 * @type {string | number | null}
 */
let strNumOrNull;

/**
 * Example 5: Union of string, number, boolean, or null
 * @type {string | number | boolean | null}
 */
let strNumBoolOrNull;

Union types allow for flexibility in specifying variable types, enabling them to accept values of multiple types.

Array Types

You can specify array types using various syntaxes in JSDoc annotations. Here are a few examples:

/**
 * Example 1: Array of numbers using square brackets syntax
 * @type {number[]}
 */
let numbersArray;

/**
 * Example 2: Array of numbers using dot notation syntax
 * @type {Array.<number>}
 */
let numbersArray2;

/**
 * Example 3: Array of numbers using angle bracket syntax
 * @type {Array<number>}
 */
let numbersArray3;

/**
 * Example 4: Array of strings using square brackets syntax
 * @type {string[]}
 */
let stringsArray;

/**
 * Example 5: Array of booleans using dot notation syntax
 * @type {Array.<boolean>}
 */
let booleanArray;

Arrays can contain elements of specific types, providing clarity and documentation for your code.

Object Literal Types

JSDoc allows specifying object literal types to document the expected structure of objects. This helps in defining the properties and their types clearly. Here are several examples:

/**
 * Example 1: Object with properties 'a' (string) and 'b' (number)
 * @type {{ a: string, b: number }}
 */
let cords;

/**
 * Example 2: Object with properties 'name' (string) and 'age' (number)
 * @type {{ name: string, age: number }}
 */
let person;

/**
 * Example 3: Object with nested structure
 * @type {{ id: number, details: { name: string, email: string } }}
 */
let user;

/**
 * Example 4: Object with optional property 'c' (boolean)
 * @type {{ a: string, b: number, c?: boolean }}
 */
let optionalProp;

/**
 * Example 5: Object with various types of properties
 * @type {{ key: string, value: number | string, isActive: boolean }}
 */
let mixedTypes;

Object literals can include nested objects, optional properties, and properties with union types, offering flexibility in how you document your JavaScript objects.

Function Types

JSDoc allows specifying function types to document the expected signatures of functions. Here are several examples using TypeScript-like syntax:

/**
 * Example 1: Function that takes two numbers and returns a number
 * @type {(x: number, y: number) => number}
 */
let add;

/**
 * Example 2: Function that takes a string and returns void
 * @type {(str: string) => void}
 */
let printMessage;

/**
 * Example 3: Function that takes no arguments and returns a boolean
 * @type {() => boolean}
 */
let isReady;

/**
 * Example 4: Function that takes an array of numbers and returns a number
 * @type {(numbers: number[]) => number}
 */
let sumArray;

/**
 * Example 5: Function that takes a callback function and returns void
 * @type {(callback: () => void) => void}
 */
let runCallback;

Function types provide clarity and documentation for functions in your JavaScript codebase.

Array of Objects

JSDoc allows specifying array types containing objects with specific properties and types. Here are several examples:

/**
 * Example 1: Array of objects with 'name' (string) and 'age' (number) properties
 * @type {{ name: string, age: number }[]}
 */
let people;

/**
 * Example 2: Array of objects with 'id' (number) and 'email' (string) properties
 * @type {{ id: number, email: string }[]}
 */
let users;

/**
 * Example 3: Array of objects with nested structure
 * @type {{ id: number, details: { name: string, email: string }}[]}
 */
let userDetails;

/**
 * Example 4: Array of objects with optional 'isActive' (boolean) property
 * @type {{ id: number, name: string, isActive?: boolean }[]}
 */
let optionalProperties;

/**
 * Example 5: Array of objects with mixed types of properties
 * @type {{ key: string, value: number | string, isActive: boolean }[]}
 */
let mixedProperties;

Arrays of objects provide clarity and documentation for complex data structures in your JavaScript codebase.

JSDoc Reference

https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html