refactor(pacakages/stdlib): add base jsdoc for each function

packages/stdlib/src/bits/flags/index.ts

@@ -1,5 +1,7 @@
 /**
- * Create a function that generates unique flags
+ * @name flagsGenerator
+ * @category Bits
+ * @description Create a function that generates unique flags
  * 
  * @returns {Function} A function that generates unique flags
  * @throws {RangeError} If more than 31 flags are created
@@ -20,7 +22,9 @@ export function flagsGenerator() {
 }
 
 /**
- * Function to combine multiple flags using the AND operator
+ * @name and
+ * @category Bits
+ * @description Function to combine multiple flags using the AND operator
  * 
  * @param {number[]} flags - The flags to combine
  * @returns {number} The combined flags
@@ -32,7 +36,9 @@ export function and(...flags: number[]) {
 }
 
 /**
- * Function to combine multiple flags using the OR operator
+ * @name or
+ * @category Bits
+ * @description Function to combine multiple flags using the OR operator
  * 
  * @param {number[]} flags - The flags to combine
  * @returns {number} The combined flags
@@ -44,7 +50,9 @@ export function or(...flags: number[]) {
 }
 
 /**
- * Function to apply the NOT operator to a flag
+ * @name not
+ * @category Bits
+ * @description Function to combine multiple flags using the XOR operator
  * 
  * @param {number} flag - The flag to apply the NOT operator to
  * @returns {number} The result of the NOT operator
@@ -56,7 +64,9 @@ export function not(flag: number) {
 }
 
 /**
- * Function to make sure a flag has a specific bit set
+ * @name has
+ * @category Bits
+ * @description Function to make sure a flag has a specific bit set
  * 
  * @param {number} flag - The flag to check
  * @param {number} other - Flag to check
@@ -69,7 +79,9 @@ export function has(flag: number, other: number) {
 }
 
 /**
- * Function to check if a flag is set
+ * @name is
+ * @category Bits
+ * @description Function to check if a flag is set
  * 
  * @param {number} flag - The flag to check
  * @returns {boolean} Whether the flag is set
@@ -81,7 +93,9 @@ export function is(flag: number) {
 }
 
 /**
- * Function to unset a flag
+ * @name unset
+ * @category Bits
+ * @description Function to unset a flag
  * 
  * @param {number} flag - Source flag
  * @param {number} other - Flag to unset
@@ -94,7 +108,9 @@ export function unset(flag: number, other: number) {
 }
 
 /**
- * Function to toggle (xor) a flag
+ * @name toggle
+ * @category Bits
+ * @description Function to toggle (xor) a flag
  * 
  * @param {number} flag - Source flag
  * @param {number} other - Flag to toggle

packages/stdlib/src/math/basic/clamp/index.test.ts

@@ -43,4 +43,39 @@ describe('clamp', () => {
     // negative range and value
     expect(clamp(-10, -100, -5)).toBe(-10);
   });
+
+  it('handle NaN and Infinity', () => {
+    // value is NaN
+    expect(clamp(NaN, 0, 100)).toBe(NaN);
+
+    // min is NaN
+    expect(clamp(50, NaN, 100)).toBe(NaN);
+
+    // max is NaN
+    expect(clamp(50, 0, NaN)).toBe(NaN);
+
+    // value is Infinity
+    expect(clamp(Infinity, 0, 100)).toBe(100);
+
+    // min is Infinity
+    expect(clamp(50, Infinity, 100)).toBe(100);
+
+    // max is Infinity
+    expect(clamp(50, 0, Infinity)).toBe(50);
+
+    // min and max are Infinity
+    expect(clamp(50, Infinity, Infinity)).toBe(Infinity);
+
+    // value is -Infinity
+    expect(clamp(-Infinity, 0, 100)).toBe(0);
+
+    // min is -Infinity
+    expect(clamp(50, -Infinity, 100)).toBe(50);
+
+    // max is -Infinity
+    expect(clamp(50, 0, -Infinity)).toBe(-Infinity);
+
+    // min and max are -Infinity
+    expect(clamp(50, -Infinity, -Infinity)).toBe(-Infinity);
+  });
 });

packages/stdlib/src/math/basic/clamp/index.ts

@@ -1,5 +1,7 @@
 /**
- * Clamps a number between a minimum and maximum value
+ * @name clamp
+ * @category Math
+ * @description Clamps a number between a minimum and maximum value
  * 
  * @param {number} value The number to clamp
  * @param {number} min Minimum value

packages/stdlib/src/math/basic/lerp/index.test.ts

@@ -1,5 +1,5 @@
 import {describe, it, expect} from 'vitest';
-import {inverseLerp, lerp} from './index';
+import {inverseLerp, lerp} from '.';
 
 describe('lerp', () => {
   it('interpolates between two values', () => {

packages/stdlib/src/math/basic/lerp/index.ts

@@ -1,5 +1,7 @@
 /**
- * Linearly interpolates between two values
+ * @name lerp
+ * @category Math
+ * @description Linearly interpolates between two values
  *
  * @param {number} start The start value
  * @param {number} end The end value
@@ -13,7 +15,9 @@ export function lerp(start: number, end: number, t: number) {
 }
 
 /**
- * Inverse linear interpolation between two values
+ * @name inverseLerp
+ * @category Math
+ * @description Inverse linear interpolation between two values
  *
  * @param {number} start The start value
  * @param {number} end The end value

packages/stdlib/src/math/basic/remap/index.test.ts

@@ -1,5 +1,5 @@
 import {describe, expect, it} from 'vitest';
-import {remap} from './index';
+import {remap} from '.';
 
 describe('remap', () => {
   it('map values from one range to another', () => {

packages/stdlib/src/math/basic/remap/index.ts

@@ -2,7 +2,9 @@ import { clamp } from '../clamp';
 import {inverseLerp, lerp} from '../lerp';
 
 /**
- * Map a value from one range to another
+ * @name remap
+ * @category Math
+ * @description Map a value from one range to another
  * 
  * @param {number} value The value to map
  * @param {number} in_min The minimum value of the input range

packages/stdlib/src/math/bigint/clampBigInt/index.test.ts

@@ -1,5 +1,5 @@
 import {describe, it, expect} from 'vitest';
-import {clampBigInt} from './index';
+import {clampBigInt} from '.';
 
 describe('clampBigInt', () => {
   it('clamp a value within the given range', () => {

packages/stdlib/src/math/bigint/clampBigInt/index.ts

@@ -2,7 +2,9 @@ import {minBigInt} from '../minBigInt';
 import {maxBigInt} from '../maxBigInt';
 
 /**
- * Clamps a bigint between a minimum and maximum value
+ * @name clampBigInt
+ * @category Math
+ * @description Clamps a bigint between a minimum and maximum value
  *
  * @param {bigint} value The number to clamp
  * @param {bigint} min Minimum value

packages/stdlib/src/math/bigint/lerpBigInt/index.test.ts

@@ -1,5 +1,5 @@
 import {describe, it, expect} from 'vitest';
-import {inverseLerpBigInt, lerpBigInt} from './index';
+import {inverseLerpBigInt, lerpBigInt} from '.';
 
 const MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
 

packages/stdlib/src/math/bigint/lerpBigInt/index.ts

@@ -1,5 +1,7 @@
 /**
- * Linearly interpolates between bigint values
+ * @name lerpBigInt
+ * @category Math
+ * @description Linearly interpolates between bigint values
  *
  * @param {bigint} start The start value
  * @param {bigint} end The end value
@@ -13,7 +15,9 @@ export function lerpBigInt(start: bigint, end: bigint, t: number) {
 }
 
 /**
- * Inverse linear interpolation between two bigint values
+ * @name inverseLerpBigInt
+ * @category Math
+ * @description Inverse linear interpolation between two bigint values
  *
  * @param {bigint} start The start value
  * @param {bigint} end The end value

packages/stdlib/src/math/bigint/maxBigInt/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { maxBigInt } from './index';
+import { maxBigInt } from '.';
 
 describe('maxBigInt', () => {
   it('returns -Infinity when no values are provided', () => {

packages/stdlib/src/math/bigint/maxBigInt/index.ts

@@ -1,5 +1,7 @@
 /**
- * Like `Math.max` but for BigInts
+ * @name maxBigInt
+ * @category Math
+ * @description Like `Math.max` but for BigInts
  *
  * @param {...bigint} values The values to compare
  * @returns {bigint} The largest value

packages/stdlib/src/math/bigint/minBigInt/index.test.ts

@@ -1,5 +1,5 @@
 import {describe, it, expect} from 'vitest';
-import {minBigInt} from './index';
+import {minBigInt} from '.';
 
 describe('minBigInt', () => {
   it('returns Infinity when no values are provided', () => {

packages/stdlib/src/math/bigint/minBigInt/index.ts

@@ -1,5 +1,7 @@
 /**
- * Like `Math.min` but for BigInts
+ * @name minBigInt
+ * @category Math
+ * @description Like `Math.min` but for BigInts
  *
  * @param {...bigint} values The values to compare
  * @returns {bigint} The smallest value

packages/stdlib/src/math/bigint/remapBigInt/index.test.ts

@@ -1,5 +1,5 @@
 import {describe, expect, it} from 'vitest';
-import {remapBigInt} from './index';
+import {remapBigInt} from '.';
 
 describe('remapBigInt', () => {
   it('map values from one range to another', () => {

packages/stdlib/src/math/bigint/remapBigInt/index.ts

@@ -2,7 +2,9 @@ import { clampBigInt } from '../clampBigInt';
 import {inverseLerpBigInt, lerpBigInt} from '../lerpBigInt';
 
 /**
- * Map a bigint value from one range to another
+ * @name remapBigInt
+ * @category Math
+ * @description Map a bigint value from one range to another
  * 
  * @param {bigint} value The value to map
  * @param {bigint} in_min The minimum value of the input range

packages/stdlib/src/patterns/behavioral/pubsub/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { PubSub } from './index';
+import { PubSub } from '.';
 
 describe('pubsub', () => {
   const event3 = Symbol('event3');

packages/stdlib/src/patterns/behavioral/pubsub/index.ts

@@ -2,7 +2,9 @@ export type Subscriber = (...args: any[]) => void;
 export type EventsRecord = Record<string | symbol, Subscriber>;
 
 /**
- * Simple PubSub implementation
+ * @name PubSub
+ * @category Patterns
+ * @description Simple PubSub implementation
  *
  * @since 0.0.2
  * 

packages/stdlib/src/structs/stack/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { Stack } from './index';
+import { Stack } from '.';
 
 describe('stack', () => {
   describe('constructor', () => {

packages/stdlib/src/structs/stack/index.ts

@@ -3,7 +3,9 @@ export type StackOptions = {
 };
 
 /**
- * Represents a stack data structure
+ * @name Stack
+ * @category Data Structures
+ * @description Represents a stack data structure
  *
  * @since 0.0.2
  *

packages/stdlib/src/text/levenshtein-distance/index.ts

@@ -1,5 +1,7 @@
 /**
- * Calculate the Levenshtein distance between two strings
+ * @name levenshteinDistance
+ * @category Text
+ * @description Calculate the Levenshtein distance between two strings
  * 
  * @param {string} left First string
  * @param {string} right Second string

packages/stdlib/src/text/template/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { templateObject } from './index';
+import { templateObject } from '.';
 
 describe('templateObject', () => {
   // it('replace template placeholders with corresponding values from args', () => {

packages/stdlib/src/text/trigram-distance/index.ts

@@ -1,7 +1,9 @@
 export type Trigrams = Map<string, number>;
 
 /**
- * Extracts trigrams from a text and returns a map of trigram to count
+ * @name trigramProfile
+ * @category Text
+ * @description Extracts trigrams from a text and returns a map of trigram to count
  * 
  * @param {string} text The text to extract trigrams
  * @returns {Trigrams} A map of trigram to count
@@ -23,7 +25,9 @@ export function trigramProfile(text: string): Trigrams {
 }
 
 /**
- * Calculates the trigram distance between two strings
+ * @name trigramDistance
+ * @category Text
+ * @description Calculates the trigram distance between two strings
  * 
  * @param {Trigrams} left First text trigram profile
  * @param {Trigrams} right Second text trigram profile

packages/stdlib/src/types/js/casts.ts

@@ -1,7 +1,11 @@
 /**
- * To string any value.
+ * @name toString
+ * @category Types
+ * @description To string any value
  * 
  * @param {any} value
  * @returns {string}
+ * 
+ * @since 0.0.2
  */
 export const toString = (value: any): string => Object.prototype.toString.call(value);

packages/stdlib/src/types/js/complex.ts

@@ -1,81 +1,121 @@
 import { toString } from '.';
 
 /**
- * Check if a value is an array.
+ * @name isFunction
+ * @category Types
+ * @description Check if a value is an array
  * 
  * @param {any} value
  * @returns {value is any[]}
+ * 
+ * @since 0.0.2
  */
 export const isArray = (value: any): value is any[] => Array.isArray(value);
 
 /**
- * Check if a value is an object.
+ * @name isObject
+ * @category Types
+ * @description Check if a value is an object
  * 
  * @param {any} value
  * @returns {value is object}
+ * 
+ * @since 0.0.2
  */
 export const isObject = (value: any): value is object => toString(value) === '[object Object]';
 
 /**
- * Check if a value is a regexp.
+ * @name isRegExp
+ * @category Types
+ * @description Check if a value is a regexp
  *
  * @param {any} value
  * @returns {value is RegExp}
+ * 
+ * @since 0.0.2
  */
 export const isRegExp = (value: any): value is RegExp => toString(value) === '[object RegExp]';
 
 /**
- * Check if a value is a date.
+ * @name isDate
+ * @category Types
+ * @description Check if a value is a date
  *
  * @param {any} value
  * @returns {value is Date}
+ * 
+ * @since 0.0.2
  */
 export const isDate = (value: any): value is Date => toString(value) === '[object Date]';
 
 /**
- * Check if a value is an error.
+ * @name isError
+ * @category Types
+ * @description Check if a value is an error
  * 
  * @param {any} value
  * @returns {value is Error}
+ * 
+ * @since 0.0.2
  */
 export const isError = (value: any): value is Error => toString(value) === '[object Error]';
 
 /**
- * Check if a value is a promise.
+ * @name isPromise
+ * @category Types
+ * @description Check if a value is a promise
  * 
  * @param {any} value
  * @returns {value is Promise<any>}
+ * 
+ * @since 0.0.2
  */
 export const isPromise = (value: any): value is Promise<any> => toString(value) === '[object Promise]';
 
 /**
- * Check if a value is a map.
+ * @name isMap
+ * @category Types
+ * @description Check if a value is a map
  * 
  * @param {any} value
  * @returns {value is Map<any, any>}
+ * 
+ * @since 0.0.2
  */
 export const isMap = (value: any): value is Map<any, any> => toString(value) === '[object Map]';
 
 /**
- * Check if a value is a set.
+ * @name isSet
+ * @category Types
+ * @description Check if a value is a set
  * 
  * @param {any} value
  * @returns {value is Set<any>}
+ * 
+ * @since 0.0.2
  */
 export const isSet = (value: any): value is Set<any> => toString(value) === '[object Set]';
 
 /**
- * Check if a value is a weakmap.
+ * @name isWeakMap
+ * @category Types
+ * @description Check if a value is a weakmap
  * 
  * @param {any} value
  * @returns {value is WeakMap<object, any>}
+ * 
+ * @since 0.0.2
  */
 export const isWeakMap = (value: any): value is WeakMap<object, any> => toString(value) === '[object WeakMap]';
 
 /**
- * Check if a value is a weakset.
+ * @name isWeakSet
+ * @category Types
+ * @description Check if a value is a weakset
  * 
  * @param {any} value
  * @returns {value is WeakSet<object>}
+ * 
+ * @since 0.0.2
  */
 export const isWeakSet = (value: any): value is WeakSet<object> => toString(value) === '[object WeakSet]';

packages/stdlib/src/types/js/primitives.ts

@@ -1,65 +1,97 @@
 import { toString } from '.';
 
 /**
- * Check if a value is a boolean.
+ * @name isObject
+ * @category Types
+ * @description Check if a value is a boolean
  * 
  * @param {any} value
  * @returns {value is boolean}
+ * 
+ * @since 0.0.2
  */
 export const isBoolean = (value: any): value is boolean => typeof value === 'boolean';
 
 /**
- * Check if a value is a function.
+ * @name isFunction
+ * @category Types
+ * @description Check if a value is a function
  * 
  * @param {any} value
  * @returns {value is Function}
+ * 
+ * @since 0.0.2
  */
 export const isFunction = <T extends Function>(value: any): value is T => typeof value === 'function';
 
 /**
- * Check if a value is a number.
+ * @name isNumber
+ * @category Types
+ * @description Check if a value is a number
  * 
  * @param {any} value
  * @returns {value is number}
+ * 
+ * @since 0.0.2
  */
 export const isNumber = (value: any): value is number => typeof value === 'number';
 
 /**
- * Check if a value is a bigint.
+ * @name isBigInt
+ * @category Types
+ * @description Check if a value is a bigint
  * 
  * @param {any} value
  * @returns {value is bigint}
+ * 
+ * @since 0.0.2
  */
 export const isBigInt = (value: any): value is bigint => typeof value === 'bigint';
 
 /**
- * Check if a value is a string.
+ * @name isString
+ * @category Types
+ * @description Check if a value is a string
  * 
  * @param {any} value
  * @returns {value is string}
+ * 
+ * @since 0.0.2
  */
 export const isString = (value: any): value is string => typeof value === 'string';
 
 /**
- * Check if a value is a symbol.
+ * @name isSymbol
+ * @category Types
+ * @description Check if a value is a symbol
  * 
  * @param {any} value
  * @returns {value is symbol}
+ * 
+ * @since 0.0.2
  */
 export const isSymbol = (value: any): value is symbol => typeof value === 'symbol';
 
 /**
- * Check if a value is a undefined.
+ * @name isUndefined
+ * @category Types
+ * @description Check if a value is a undefined
  * 
  * @param {any} value
  * @returns {value is undefined}
+ * 
+ * @since 0.0.2
  */
 export const isUndefined = (value: any): value is undefined => toString(value) === '[object Undefined]';
 
 /**
- * Check if a value is a null.
+ * @name isNull
+ * @category Types
+ * @description Check if a value is a null
  * 
  * @param {any} value
  * @returns {value is null}
+ * 
+ * @since 0.0.2
  */
 export const isNull = (value: any): value is null => toString(value) === '[object Null]';

packages/stdlib/src/utils/index.ts

@@ -1,13 +1,21 @@
 /**
- * Returns the current timestamp
+ * @name timestamp
+ * @category Utils
+ * @description Returns the current timestamp
  * 
  * @returns {number} The current timestamp
+ * 
+ * @since 0.0.2
  */
 export const timestamp = () => Date.now();
 
 /**
- * No operation function
+ * @name noop
+ * @category Utils
+ * @description A function that does nothing
  * 
  * @returns {void} Nothing
+ * 
+ * @since 0.0.2
  */
 export const noop = () => {};