diff --git a/content/2.functions/actions.md b/content/2.functions/actions.md index 3d2ee7c2..e67d3c33 100644 --- a/content/2.functions/actions.md +++ b/content/2.functions/actions.md @@ -2,9 +2,101 @@ #### A collection of useful actions -## // subtitle: Page Actions -// description: A collection of useful actions +### +Scrolls to the element with the specified ID. @example scrollToAnchor('#my-anchor') -## // subtitle: Form Actions -// description: A collection of useful actions +```js [js] +scrollToAnchor('#my-anchor') +``` + +### +Smoothly scroll to the top of the page @example scrollToTop() + +```js [js] +scrollToTop() +``` + +### +Smoothly scroll to the bottom of the page @example scrollToBottom() + +```js [js] +scrollToBottom() +``` + +### +Toggles the body scroll with the specified class name @example toggleBodyScroll('overflow-hidden') + +```js [js] +toggleBodyScroll('overflow-hidden') +``` + +### +Toggles the element scroll @example toggleElementScroll(document.querySelector('#my-element')) + +```js [js] +toggleElementScroll(document.querySelector('#my-element')) +``` + +### +Copies a text to the clipboard @example copyToClipboard() + +```js [js] +copyToClipboard() +``` + +### +Toggles the fullscreen mode @example toggleFullScreen() + +```js [js] +toggleFullScreen() +``` + +### +Toggles the dark mode @example toggleDarkMode() + +```js [js] +toggleDarkMode() +``` + +### +Redirects to a new URL @example redirect('https://example.com') + +```js [js] +redirect('https://example.com') +``` + +### +Resets a form @example resetForm(document.querySelector('form')) + +```js [js] +resetForm(document.querySelector('form')) +``` + +### +Focuses on an element @example focusOn(document.querySelector('#my-element')) + +```js [js] +focusOn(document.querySelector('#my-element')) +``` + +### +Focuses on the first element @example focusOnFirst(document.querySelector('#my-element')) + +```js [js] +focusOnFirst(document.querySelector('#my-element')) +``` + +### +Focuses on the last element @example focusOnLast(document.querySelector('#my-element')) + +```js [js] +focusOnLast(document.querySelector('#my-element')) +``` + +### +Sets up a keyboard trap within an HTML element, allowing the focus to cycle between the first and last focusable elements when the Tab key is pressed. @example focusTrap(document.querySelector('#my-element')) + +```js [js] +focusTrap(document.querySelector('#my-element')) +``` diff --git a/content/2.functions/detections.md b/content/2.functions/detections.md index 09e343f3..9b15941f 100644 --- a/content/2.functions/detections.md +++ b/content/2.functions/detections.md @@ -2,36 +2,290 @@ #### A collection of detections for common data types -### detectDevice -Detect the current device type (Mobile or Desktop) +### export function detectDevice +Detect the current device type (Mobile or Desktop) @example detectDevice() @returns `Mobile` or `Desktop` -### detectOS -Detect the current operating system +```js [js] +detectDevice() +``` -### detectBrowser -Detects the user's browser based on the user agent string. +### export function detectOS +Detect the current operating system @example detectOS() @returns `Windows`, `Mac`, `Linux`, `UNIX`, or `Unknown` -### detectActiveBrowser -Detect if the browser window is currently active or hidden. +```js [js] +detectOS() +``` -### detectColorScheme -Detect the current color scheme (Light or Dark) +### export function detectBrowser +Detects the user's browser based on the user agent string. @example detectBrowser() @returns `Chrome`, `Firefox`, `Safari`, `Opera`, `Edge`, `IE`, or `Unknown` -### detectBrowserLanguage -Detect the current browser language +```js [js] +detectBrowser() +``` -### detectGeolocation -Detect the current user's location +### export function detectActiveBrowser +Detect if the browser window is currently active or hidden. @example detectActiveBrowser() -### detectDeviceOrientation -Detect the currect device orientation +```js [js] +detectActiveBrowser() +``` -### detectDeviceMotion -Detect the current device motion +### export function detectColorScheme +Detect the current color scheme (Light or Dark) @example detectColorScheme() @returns `Light` or `Dark` -### detectTailwindContainerBreakpoint -Detect the current container breakpoint based on Tailwind CSS breakpoints +```js [js] +detectColorScheme() +``` -### detectScrollPosition -Detect the current scroll position of the window +### export function detectBrowserLanguage +Detect the current browser language @example detectBrowserLanguage() + +```js [js] +detectBrowserLanguage() +``` + +### export function detectGeolocation +Detect the current user's location @example detectUserLocation() @returns `US`, `UK`, `CA`, `AU`, `NZ`, `EU`, `Unknown` + +```js [js] +detectUserLocation() +``` + +### export function detectUserTimezone +Detect the current user's Timezone @example detectUserTimezone() + +```js [js] +detectUserTimezone() +``` + +### export function detectDeviceOrientation +Detect the currect device orientation @example detectDeviceOrientation() + +```js [js] +detectDeviceOrientation() +``` + +### export function detectDeviceMotion +Detect the current device motion @example detectDeviceMotion() + +```js [js] +detectDeviceMotion() +``` + +### +Detect the browser's window size @example detectWindowSize() + +```js [js] +detectWindowSize() +``` + +### +Detect the screen or monitor size @example detectScreenSize() + +```js [js] +detectScreenSize() +``` + +### +Detect the container size via ID @example detectContainerSize('container') + +```js [js] +detectContainerSize('container') +``` + +### export function detectTailwindBreakpoint +Detect the current breakpoint based on Tailwind CSS breakpoints @example detectTailwindBreakpoint() + +```js [js] +detectTailwindBreakpoint() +``` + +### export function detectTailwindContainerBreakpoint +Detect the current container breakpoint based on Tailwind CSS breakpoints @example detectTailwindContainerBreakpoint('container') + +```js [js] +detectTailwindContainerBreakpoint('container') +``` + +### +Detect the current scroll position of the window @example detectScrollPosition() + +```js [js] +detectScrollPosition() +``` + +### +Detect the current mouse position within the window @example detectMousePosition(event) + +```js [js] +detectMousePosition(event) +``` + +### +Detect the current mouse position within a container via ID @example detectRelativeMousePosition('container', event) + +```js [js] +detectRelativeMousePosition('container', event) +``` + +### export function detectNetworkStatus +Detect the current network status of the user (Online or Offline) @example detectNetworkStatus() + +```js [js] +detectNetworkStatus() +``` + +### +Detect the current memory status of the user (RAM) @example detectMemoryStatus() + +```js [js] +detectMemoryStatus() +``` + +### export function detectPerformance +Detect the current performance status of the user (CPU, RAM, etc.) @example detectPerformance() + +```js [js] +detectPerformance() +``` + +### +Detect the current storage status of the user (Local Storage, Session Storage) @example detectStorage() + +```js [js] +detectStorage() +``` + +### +Returns a cookie value by name @example detectCookie('name') + +```js [js] +detectCookie('name') +``` + +### +Returns a local storage value by name and parses it into JSON @example detectLocalStorage('name') + +```js [js] +detectLocalStorage('name') +``` + +### +Returns a session storage value by name and parses it into JSON @example detectSessionStorage('name') + +```js [js] +detectSessionStorage('name') +``` + +### +Returns a value from the URL by name @example detectURLParameters('http://url.com/page?name=Adam&surname=Smith') + +```js [js] +detectURLParameters('http://url.com/page?name=Adam&surname=Smith') +``` + +### +Returns a value from the URL hash by name @example detectURLHashParameters() + +```js [js] +detectURLHashParameters() +``` + +### +Retrieves and returns the parameters from the URL search query string @example detectURLSearchParameters() + +```js [js] +detectURLSearchParameters() +``` + +### +Returns the current URL @example detectURL() + +```js [js] +detectURL() +``` + +### +Returns the current domain @example detectDomain() + +```js [js] +detectDomain() +``` + +### +Returns the current IP address @example detectIP() + +```js [js] +detectIP() +``` + +### +Returns the current port @example detectPort() + +```js [js] +detectPort() +``` + +### +Returns the current protocol (HTTP or HTTPS) @example detectProtocol() + +```js [js] +detectProtocol() +``` + +### +Returns the URL of the referring page (the page that linked to the current page) @example detectReferrer() + +```js [js] +detectReferrer() +``` + +### export function detectCachedData +Retrieves cached entries and optionally filters the entries based on a provided key @example detectCachedData('abc') + +```js [js] +detectCachedData('abc') +``` + +### +Detects if the element is currently in the viewport @example isInViewport(element) + +```js [js] +isInViewport(element) +``` + +### +Detects if the element is currently in the container via ID @example isInContainer(element, 'container') + +```js [js] +isInContainer(element, 'container') +``` + +### +Detects if the element is overflowing vertically @example isOverflowingY(element) + +```js [js] +isOverflowingY(element) +``` + +### +Detects if the element is overflowing horizontally @example isOverflowingX(element) + +```js [js] +isOverflowingX(element) +``` + +### +Detects if the element is scrollable (overflowing vertically or horizontally) @example isScrollable(element) + +```js [js] +isScrollable(element) +``` + +### +Detects if the elements is an HTML element @example isElement(element) + +```js [js] +isElement(element) +``` diff --git a/content/2.functions/formatters.md b/content/2.functions/formatters.md index bd0fbf82..3183edb2 100644 --- a/content/2.functions/formatters.md +++ b/content/2.functions/formatters.md @@ -2,63 +2,45 @@ #### A collection of formatters for common data types -### formatCurrency -Format numbers into local currency +### export function formatCurrency +Format numbers into local currency @example formatCurrency(1234.56) @returns $1,234.56 ```js [js] formatCurrency(1234.56) ``` -::example{:code=formatCurrency(1234.56)} -:: - -### formatValuation -Format numbers into valuations displayed in thounsands, millions or billions +### export function formatValuation +Format numbers into valuations displayed in thounsands, millions or billions @example formatValuation(1234567890) @returns $1.23B ```js [js] formatValuation(1234567890) ``` -::example{:code=formatValuation(1234567890)} -:: - -### formatTime -Format time into hours, minutes, and seconds +### export function formatTime +Format time into hours, minutes, and seconds @example formatTime(3723) @returns 1hr 2min 3s ```js [js] formatTime(3723) ``` -::example{:code=formatTime(3723)} -:: - -### formatDatetime -Format Unix timestamp into a datetime string +### export function formatDatetime +Format Unix timestamp into a datetime string @example formatDatetime(1619097600) @returns 2021-04-22 00:00:00 ```js [js] formatDatetime(1619097600) ``` -::example{:code=formatDatetime(1619097600)} -:: - -### formatPercentage -Format a number into a percentage +### export function formatPercentage +Format a number into a percentage @example formatPercentage(0.1234) @returns 12.34% ```js [js] formatPercentage(0.1234) ``` -::example{:code=formatPercentage(0.1234)} -:: - -### formatList -Create a string of comma-separated values from an array of strings with an optional conjunction. +### export function formatList +Create a string of comma-separated values from an array of strings with an optional conjunction. @param items - The array of strings. @param limit - The maximum number of items to include before truncating. @param conjunction - The conjunction before the last item e.g. "and" or "or". @example commaList(['one', 'two', 'three']) @returns one, two and three ```js [js] commaList(['one', 'two', 'three']) ``` -::example{:code=commaList(['one', 'two', 'three'])} -:: - diff --git a/content/2.functions/generators.md b/content/2.functions/generators.md index 756a43f0..d6773e83 100644 --- a/content/2.functions/generators.md +++ b/content/2.functions/generators.md @@ -2,9 +2,17 @@ #### A collection of generators -### generateShortId -Generate a unique short ID based on the current timestamp +### export function generateShortId +Generate a unique short ID based on the current timestamp @example generateShortId(36) @returns 1HR2MIN3S -### generateInitials -Generate initials from any string +```js [js] +generateShortId(36) +``` + +### export function generateInitials +Generate initials from any string @example generateInitials('John Doe') @returns JD + +```js [js] +generateInitials('John Doe') +``` diff --git a/content/2.functions/modifiers.md b/content/2.functions/modifiers.md index 44c11c31..32c6c5c7 100644 --- a/content/2.functions/modifiers.md +++ b/content/2.functions/modifiers.md @@ -2,120 +2,367 @@ #### Modifiers are a key feature of Mods that allow you to easily modify and enhance your content. They are small pieces of code that can be applied to your JS to add functionality, validation or style. -### widont -Adds a space between the last two words in a string. +### export function widont +Adds a space between the last two words in a string. @example widont('Cool cool cool') @returns cool cool cool -### stripHtml -Strip HTML tags from a string. +```js [js] +widont('Cool cool cool') +``` -### escapeHtml -Escape HTML entities in a string. +### export function stripHtml +Strip HTML tags from a string. @example stripHtml('

Hello World

') @returns Hello World -### unescapeHtml -Unescape HTML entities in a string. +```js [js] +stripHtml('

Hello World

') +``` -### stripTags -Strip HTML tags from a string. +### export function escapeHtml +Escape HTML entities in a string. @example escapeHtml('

Hello World

') @returns <p>Hello World</p> -### slugify -Converts a string to-a-slug. +```js [js] +escapeHtml('

Hello World

') +``` -### deslugify -Converts a slug to a string. +### export function unescapeHtml +Unescape HTML entities in a string. @example unescapeHtml('<p>Hello World</p>') @returns

Hello World

-### truncate -Truncates a string to a specified length of characters. +```js [js] +unescapeHtml('<p>Hello World</p>') +``` -### truncateWords -Truncates a string by a number of words +### export function stripTags +Strip HTML tags from a string. @example stripTags('

Hello World

') @returns Hello World -### countWords -Counts the number of words in a string. +```js [js] +stripTags('

Hello World

') +``` -### countCharacters -Counts the number of characters in a string. +### export function slugify +Converts a string to-a-slug. @example slugify('Hello World') @returns hello-world -### countLines -Counts the number of lines in a string. +```js [js] +slugify('Hello World') +``` -### stripWhitespace -Strips whitespace from a string. +### export function deslugify +Converts a slug to a string. @example deslugify('hello-world') @returns hello world -### stripNumbers -Strips numbers from a string. +```js [js] +deslugify('hello-world') +``` -### stripPunctuation -Strips punctuation from a string. +### export function truncate +Truncates a string to a specified length of characters. @example truncate('Hello World', 5) @returns Hello... -### stripSymbols -Strips symbols from a string. +```js [js] +truncate('Hello World', 5) +``` -### stripEmojis -Strips emojis from a string (requires ES6 Unicode support) 🦊. +### export function truncateWords +Truncates a string by a number of words @example truncateWords('Hello World', 1) @returns Hello... -### readingTime -Returns the reading time of a string in Hours, Minutes, and Seconds. +```js [js] +truncateWords('Hello World', 1) +``` -### pluralize -Adds plurals to a string. +### export function countWords +Counts the number of words in a string. @example countWords('Hello World') @returns 2 -### singularize -Removes plurals from a string. +```js [js] +countWords('Hello World') +``` -### ordinalize -Converts a number to a string with ordinal suffix. +### export function countCharacters +Counts the number of characters in a string. @example countCharacters('Hello World') @returns 11 -### humanize -Replaces underscores with spaces and capitalizes the first letter of each word. +```js [js] +countCharacters('Hello World') +``` -### camelCase -Removes spaces and capitalizes the first letter of each word except for the first word. +### export function countLines +Counts the number of lines in a string. @example countLines('Hello World') @returns 1 -### pascalCase -Removes spaces and capitalizes the first letter of each word. +```js [js] +countLines('Hello World') +``` -### snakeCase -Replaces spaces with underscores and converts to lowercase. +### export function stripWhitespace +Strips whitespace from a string. @example stripWhitespace('Hello World') @returns HelloWorld -### kebabCase -Replaces spaces with hyphens and converts to lowercase. +```js [js] +stripWhitespace('Hello World') +``` -### titleCase -Converts to title case by capitalizing the first letter of each word. +### export function stripNumbers +Strips numbers from a string. @example stripNumbers('Hello World 123') @returns Hello World -### sentenceCase -Converts to sentence case by capitalizing the first letter of the first word. +```js [js] +stripNumbers('Hello World 123') +``` -### startWith -Adds a prefix to a string if it doesn't already start with the prefix. +### export function stripPunctuation +Strips punctuation from a string. @example stripPunctuation('Hello World!') @returns Hello World -### startWithout -Removes a prefix from a string if it starts with the prefix. +```js [js] +stripPunctuation('Hello World!') +``` -### endWith -Adds a suffix to a string if it doesn't already end with the suffix. +### export function stripSymbols +Strips symbols from a string. @example stripSymbols('Hello World!') @returns Hello World -### endWithout -Removes a suffix from a string if it ends with the suffix. +```js [js] +stripSymbols('Hello World!') +``` -### surround -Adds a prefix and suffix to a string if it doesn't already start and end with them. +### export function stripEmojis +Strips emojis from a string (requires ES6 Unicode support) 🦊. @example stripEmojis('Hello World! 🦊') @returns Hello World! -### title -Converts a string to title case following the Chicago Manual of Style rules. +```js [js] +stripEmojis('Hello World! 🦊') +``` -### splitByWords -Wraps each word in a string with a span tag. +### export function readingTime +Returns the reading time of a string in Hours, Minutes, and Seconds. @example readingTime('Once, in a vibrant online forum, lived Mod Max, guardian of digital harmony. Max cherished his old scooter, Swift, a symbol of freedom. Navigating both virtual and real worlds, they became legends. Trolls quivered, posts flourished, and lanes whizzed by. Swift’s wheels spun tales, and Max’s keys kept peace. Together, they discovered uncharted threads and hidden lanes. Their journey, an endless adventure, painted pixels and pavements with stories of unity and exhilaration, leaving a trail for all in the intertwined realms of screens and streets.') @returns 1 minute -### list -Creates an array of list items (`
  • `) from an array of strings. +```js [js] +readingTime('Once, in a vibrant online forum, lived Mod Max, guardian of digital harmony. Max cherished his old scooter, Swift, a symbol of freedom. Navigating both virtual and real worlds, they became legends. Trolls quivered, posts flourished, and lanes whizzed by. Swift’s wheels spun tales, and Max’s keys kept peace. Together, they discovered uncharted threads and hidden lanes. Their journey, an endless adventure, painted pixels and pavements with stories of unity and exhilaration, leaving a trail for all in the intertwined realms of screens and streets.') +``` -### shuffle -Shuffles an array. +### export function pluralize +Adds plurals to a string. @example pluralize('scooter', 10) @returns scooters -### last -Returns the last item in an array. +```js [js] +pluralize('scooter', 10) +``` -### nth -Returns the nth item in an array. +### export function singularize +Removes plurals from a string. @example singularize('scooters') @returns scooter + +```js [js] +singularize('scooters') +``` + +### export function ordinalize +Converts a number to a string with ordinal suffix. @example ordinalize(1) @returns 1st + +```js [js] +ordinalize(1) +``` + +### export function humanize +Replaces underscores with spaces and capitalizes the first letter of each word. @example humanize('hello_world') @returns Hello World + +```js [js] +humanize('hello_world') +``` + +### export function camelCase +Removes spaces and capitalizes the first letter of each word except for the first word. @example camelCase('hello world') @returns helloWorld + +```js [js] +camelCase('hello world') +``` + +### export function pascalCase +Removes spaces and capitalizes the first letter of each word. @example pascalCase('hello world') @returns HelloWorld + +```js [js] +pascalCase('hello world') +``` + +### export function snakeCase +Replaces spaces with underscores and converts to lowercase. @example snakeCase('hello world') @returns hello_world + +```js [js] +snakeCase('hello world') +``` + +### export function kebabCase +Replaces spaces with hyphens and converts to lowercase. @example titleize('Hello World') @returns hello-world + +```js [js] +titleize('Hello World') +``` + +### export function titleCase +Converts to title case by capitalizing the first letter of each word. @example titleCase('hello world') @returns Hello World + +```js [js] +titleCase('hello world') +``` + +### export function sentenceCase +Converts to sentence case by capitalizing the first letter of the first word. @example sentenceCase('hello world') @returns Hello world + +```js [js] +sentenceCase('hello world') +``` + +### export function startWith +Adds a prefix to a string if it doesn't already start with the prefix. @example startWith('usemods.com', 'https://') @returns https://usemods.com + +```js [js] +startWith('usemods.com', 'https://') +``` + +### export function startWithout +Removes a prefix from a string if it starts with the prefix. @example startWithout('https://usemods.com', 'https://') @returns usemods.com + +```js [js] +startWithout('https://usemods.com', 'https://') +``` + +### export function endWith +Adds a suffix to a string if it doesn't already end with the suffix. @example endWith('https://usemods', '.com') @returns https://usemods.com + +```js [js] +endWith('https://usemods', '.com') +``` + +### export function endWithout +Removes a suffix from a string if it ends with the suffix. @example endWithout('https://usemods.com.au', '.au') @returns https://usemods.com + +```js [js] +endWithout('https://usemods.com.au', '.au') +``` + +### export function surround +Adds a prefix and suffix to a string if it doesn't already start and end with them. @param text - The string to surround. @param prefix - The prefix to add. @param suffix - The suffix to add. @example surround('https://', 'usemods', '.com') @returns https://usemods.com + +```js [js] +surround('https://', 'usemods', '.com') +``` + +### export function title +Converts a string to title case following the Chicago Manual of Style rules. @reference https://www.chicagomanualofstyle.org/book/ed17/frontmatter/toc.html @example title('the quick brown fox jumps over the lazy dog') @returns The Quick Brown Fox Jumps over the Lazy Dog + +```js [js] +title('the quick brown fox jumps over the lazy dog') +``` + +### export function splitByWords +Wraps each word in a string with a span tag. @example splitByWords('Hello World. How are you?') @returns Hello world. How are you? + +```js [js] +splitByWords('Hello World. How are you?') +``` + +### export function list +Creates an array of list items (`
  • `) from an array of strings. @example list(['one', 'two', 'three']) @returns + +```js [js] +list(['one', 'two', 'three']) +``` + +### export function shuffle +Shuffles an array. @example shuffle(['one', 'two', 'three']) @returns ['three', 'one', 'two'] + +```js [js] +shuffle(['one', 'two', 'three']) +``` + +### +Returns unique array values with an optional property to pluck. @param items - The array of items. @param property - The property to pluck (optional). @example unique(['one', 'two', 'three', 'one']) @returns ['one', 'two', 'three'] + +```js [js] +unique(['one', 'two', 'three', 'one']) +``` + +### export function difference +Returns the difference between two arrays. @example difference(['one', 'two', 'three'], ['one', 'two']) @returns ['three'] + +```js [js] +difference(['one', 'two', 'three'], ['one', 'two']) +``` + +### export function first +Returns the first item in an array. @example first(['one', 'two', 'three']) @returns one + +```js [js] +first(['one', 'two', 'three']) +``` + +### export function last +Returns the last item in an array. @example last(['one', 'two', 'three']) @returns three + +```js [js] +last(['one', 'two', 'three']) +``` + +### export function nth +Returns the nth item in an array. @example nth(['one', 'two', 'three'], 1) @returns two + +```js [js] +nth(['one', 'two', 'three'], 1) +``` + +### export function offset +Offset the first item in an array. @example offset(['one', 'two', 'three'], 1) @returns ['two', 'three'] + +```js [js] +offset(['one', 'two', 'three'], 1) +``` + +### +Groups an array of objects by a property. @example group([{ name: 'one' }, { name: 'two' }, { name: 'one' }], 'name') @returns { one: [{ name: 'one' }, { name: 'one' }], two: [{ name: 'two' }] } + +```js [js] +group([{ name: 'one' }, { name: 'two' }, { name: 'one' }], 'name') +``` + +### export function groupBy +Chunks an array into sections of a specified size. @example chunk(['one', 'two', 'three', 'four', 'five'], 2) @returns [['one', 'two'], ['three', 'four'], ['five']] + +```js [js] +chunk(['one', 'two', 'three', 'four', 'five'], 2) +``` + +### export function flatten +Flatten an array of arrays. @example flatten([['one', 'two'], ['three', 'four'], ['five']]) @returns ['one', 'two', 'three', 'four', 'five'] + +```js [js] +flatten([['one', 'two'], ['three', 'four'], ['five']]) +``` + +### export function without +Returns an array with a filtered out property. @example without([{ name: 'one', food: 'apple' }, { name: 'two', food: 'grape' }, { name: 'one', food: 'pear' }], 'name') @returns [{ food: 'apple' }, { food: 'grape' }, { food: 'pear' }] + +```js [js] +without([{ name: 'one', food: 'apple' }, { name: 'two', food: 'grape' }, { name: 'one', food: 'pear' }], 'name') +``` + +### export function combine +Combine two or more arrays @example combine(['one', 'two'], ['three', 'four'], ['five']) @returns ['one', 'two', 'three', 'four', 'five'] + +```js [js] +combine(['one', 'two'], ['three', 'four'], ['five']) +``` + +### +Combine two or more unique arrays @example combineUnique(['one', 'two'], ['three', 'four', 'two'], ['five', 'one']) @returns ['one', 'two', 'three', 'four', 'five'] + +```js [js] +combineUnique(['one', 'two'], ['three', 'four', 'two'], ['five', 'one']) +``` + +### +Combine two or more arrays or objects without a property. @example combineWithout({ id: 1, name: 'A' }, { id: 2, name: 'B' }, { id: 3, name: 'C' }, 'id') @returns [1, 2, 3] + +```js [js] +combineWithout({ id: 1, name: 'A' }, { id: 2, name: 'B' }, { id: 3, name: 'C' }, 'id') +``` + +### export function reverse +Reverse an array. @example reverse(['one', 'two', 'three']) @returns ['three', 'two', 'one'] + +```js [js] +reverse(['one', 'two', 'three']) +``` + +### +Sort an array by a property. @example sortBy([{ name: 'John', age: 25 },{ name: 'Jane', age: 30 },{ name: 'Jill', age: 20 }], 'age') @returns [{ name: 'Jill', age: 20 },{ name: 'John', age: 25 },{ name: 'Jane', age: 30 }] + +```js [js] +sortBy([{ name: 'John', age: 25 },{ name: 'Jane', age: 30 },{ name: 'Jill', age: 20 }], 'age') +``` diff --git a/content/2.functions/numbers.md b/content/2.functions/numbers.md index cdf4eee0..4da0dfa0 100644 --- a/content/2.functions/numbers.md +++ b/content/2.functions/numbers.md @@ -1,41 +1,123 @@ +# + #### This file contains functions that are related to numbers. -### random -Generates a random integer between the specified minimum and maximum values. +### export function random +Generates a random integer between the specified minimum and maximum values. @example random(1, 10) @returns 5 + +```js [js] +random(1, 10) +``` + +### export function sum +Calculates the sum of an array of numbers. @example sum([1, 2, 3]) @returns 6 + +```js [js] +sum([1, 2, 3]) +``` + +### export function mean +Calculates the mean of an array of numbers. @example average([1, 2, 3]) @returns 2 + +```js [js] +average([1, 2, 3]) +``` + +### export function average +Calculates the mean of an array of numbers. @example average([1, 2, 3]) @returns 2 + +```js [js] +average([1, 2, 3]) +``` + +### export function median +Calculates the median of an array of numbers. @example median([1, 2, 3]) @returns 2 + +```js [js] +median([1, 2, 3]) +``` + +### export function mode +Calculates the mode of an array of numbers. @example mode([1, 2, 2, 3]) @returns 2 + +```js [js] +mode([1, 2, 2, 3]) +``` + +### export function min +Finds the minimum value in an array of numbers. @example min([1, 2, 3]) @returns 1 + +```js [js] +min([1, 2, 3]) +``` + +### export function max +Finds the maximum value in an array of numbers. @example max([1, 2, 3]) @returns 3 + +```js [js] +max([1, 2, 3]) +``` + +### export function clamp +Clamps a number between the specified minimum and maximum values. @example clamp(1, 10, 20) @returns 10 + +```js [js] +clamp(1, 10, 20) +``` + +### +Returns the minimum and maximum values in an array of numbers. @example minMax([1, 2, 3, 4, 5]) @returns [1, 5] + +```js [js] +minMax([1, 2, 3, 4, 5]) +``` + +### export function range +Returns the difference between two values, expressed as a positive number. @example range(-10, -20) @returns 10 + +```js [js] +range(-10, -20) +``` -### sum -Calculates the sum of an array of numbers. +### export function rangeAsPercentage +Returns the difference between two values, as a percentage. @example differenceAsPercentage(10, 20) @returns 100 -### mean -Calculates the mean of an array of numbers. +```js [js] +differenceAsPercentage(10, 20) +``` -### average -Calculates the mean of an array of numbers. +### export function percentage +Returns the percentage of a value, relative to another value. @example percentage(10, 100) @returns 10 -### median -Calculates the median of an array of numbers. +```js [js] +percentage(10, 100) +``` -### mode -Calculates the mode of an array of numbers. +### export function standardDeviation +Returns the standard deviation of an array of numbers. @example standardDeviation([1, 2, 3, 20, 120, 2000]) @returns 0.5 -### max -Finds the maximum value in an array of numbers. +```js [js] +standardDeviation([1, 2, 3, 20, 120, 2000]) +``` -### clamp -Clamps a number between the specified minimum and maximum values. +### export function skewness +Returns the measure of asymmetry of the probability distribution of an array of numbers. The skewness value can be positive, zero, negative, or undefined. @example skewness([1, 2, 3, 20, 120, 2000]) @returns 2.5 -### minMax -Returns the minimum and maximum values in an array of numbers. +```js [js] +skewness([1, 2, 3, 20, 120, 2000]) +``` -### rangeAsPercentage -Returns the difference between two values, as a percentage. +### +Return the frequency of all values (numbers, string or boolean) in an array as an object @example frequency([1, 3, 2, 3, 3, 3, 'a', 'b', 'c', 'c']) @returns { '1': 1, '2': 1, '3': 4, a: 1, b: 1, c: 2 } -### percentage -Returns the percentage of a value, relative to another value. +```js [js] +frequency([1, 3, 2, 3, 3, 3, 'a', 'b', 'c', 'c']) +``` -### standardDeviation -Returns the standard deviation of an array of numbers. +### +Returns the fequency of a property value in an array @example frequencyOfPropert([1, 3, 2, 3, 3, 3, 'a', 'b', 'c', 'c'], 3) @returns 4 -### skewness -Returns the measure of asymmetry of the probability distribution of an array of numbers. The skewness value can be positive, zero, negative, or undefined. +```js [js] +frequencyOfPropert([1, 3, 2, 3, 3, 3, 'a', 'b', 'c', 'c'], 3) +``` diff --git a/content/2.functions/validators.md b/content/2.functions/validators.md index db5e7d4c..7e780555 100644 --- a/content/2.functions/validators.md +++ b/content/2.functions/validators.md @@ -2,135 +2,311 @@ #### A collection of validators for common data types -### isEmail -Check if the input is a valid email address. +### export function isEmail +Check if the input is a valid email address. @example isEmail('hello@usemods.com') @returns true -### isNumber -Check if the input is a valid number. +```js [js] +isEmail('hello@usemods.com') +``` -### isURL -Check if the input is a valid URL. +### export function isNumber +Check if the input is a valid number. @example isNumber('123') @returns true -### isUUID -Check if the input is a valid UUID. +```js [js] +isNumber('123') +``` -### isJSON -Check if the input is a valid JSON string. +### export function isURL +Check if the input is a valid URL. @example isURL('https://usemods.com') @returns true -### isHex -Check if the input is a valid hexadecimal color code. +```js [js] +isURL('https://usemods.com') +``` -### isEmpty -Check if the input is an empty string. +### export function isUUID +Check if the input is a valid UUID. @example isUUID('c9bf9e57-1685-4c89-bafb-ff5af830be8a') @returns true -### isAlpha -Check if the input contains only alphabetic characters. +```js [js] +isUUID('c9bf9e57-1685-4c89-bafb-ff5af830be8a') +``` -### isAlphanumeric -Check if the input contains only alphanumeric characters. +### export function isJSON +Check if the input is a valid JSON string. @example isJSON('{"hello": "world"}') @returns true -### isArray -Check if the input is an array. +```js [js] +isJSON('{"hello": "world"}') +``` -### isObject -Check if the input is an object. +### export function isHex +Check if the input is a valid hexadecimal color code. @example isHex('#fff') @returns true -### isBoolean -Check if the input is a boolean value. +```js [js] +isHex('#fff') +``` -### isFunction -Check if the input is a function. +### export function isEmpty +Check if the input is an empty string. @example isEmpty('') @returns true -### isUndefined -Check if the input is undefined. +```js [js] +isEmpty('') +``` -### isNull -Check if the input is null. +### export function isAlpha +Check if the input contains only alphabetic characters. @example isAlpha('hello') @returns true -### isDate -Check if the input is a valid Date object. +```js [js] +isAlpha('hello') +``` -### isError -Check if the input is an Error object with a defined message. +### export function isAlphanumeric +Check if the input contains only alphanumeric characters. @example isAlphanumeric('hello123') @returns true -### isTime -Check if the input is a valid time in HH:mm format. +```js [js] +isAlphanumeric('hello123') +``` -### isLeapYear -Check if the input year is a leap year. +### export function isArray +Check if the input is an array. @example isArray([1, 2, 3]) @returns true -### isPromise -Check if the input is a Promise object. +```js [js] +isArray([1, 2, 3]) +``` -### isSet -Check if the input is a Set object. +### export function isObject +Check if the input is an object. @example isObject({ hello: 'world' }) @returns true -### isMap -Check if the input is a Map object. +```js [js] +isObject({ hello: 'world' }) +``` -### isEven -Check if the number is even. +### export function isBoolean +Check if the input is a boolean value. @example isBoolean(true) @returns true -### isOdd -Check if the number is odd. +```js [js] +isBoolean(true) +``` -### isPositive -Check if the number is positive. +### export function isFunction +Check if the input is a function. @example isFunction(() => {}) @returns true -### isNegative -Check if the number is negative. +```js [js] +isFunction(() => {}) +``` -### isZero -Check if the number is zero. +### export function isUndefined +Check if the input is undefined. @example isUndefined(undefined) @returns true -### isPrime -Check if the number is a prime number. +```js [js] +isUndefined(undefined) +``` -### isOptimusPrime -Check if the string is equal to "Optimus Prime". +### export function isNull +Check if the input is null. @example isNull(null) @returns true -### isPalindrome -Check if the string is a palindrome. +```js [js] +isNull(null) +``` -### isInteger -Check if the number is an integer. +### export function isDate +Check if the input is a valid Date object. @example isDate(new Date()) @returns true -### isFloat -Check if the number is a float. +```js [js] +isDate(new Date()) +``` -### isBetween -Check if the number is between the specified range. +### export function isError +Check if the input is an Error object with a defined message. @example isError(new Error('hello')) @returns true -### isDivisibleBy -Check if the number is divisible by the specified number. +```js [js] +isError(new Error('hello')) +``` -### isCreditCardNumber -Check if the input is a valid credit card number. +### export function isTime +Check if the input is a valid time in HH:mm format. @example isTime('12:00') @returns true -### isIPAddress -Check if the input is a valid IP address. +```js [js] +isTime('12:00') +``` -### isMACAddress -Check if the input is a valid MAC address. +### export function isLeapYear +Check if the input year is a leap year. @example isLeapYear(2020) @returns true -### isLatLng -Check if the input is a valid latitude-longitude coordinate in the format lat,lng or lat,lng. +```js [js] +isLeapYear(2020) +``` -### isLatitude -Check if the input is a valid latitude coordinate. +### export function isPromise +Check if the input is a Promise object. @example isPromise(new Promise(() => {})) @returns true -### isLongitude -Check if the input is a valid longitude coordinate. +```js [js] +isPromise(new Promise(() => {})) +``` -### isPort -Check if the input is a valid port number. +### export function isSet +Check if the input is a Set object. @example isSet(new Set()) @returns true -### isPresent -Checks if a property and value pair exists in an object. +```js [js] +isSet(new Set()) +``` -### hasProperties -Check if a property exists in an object without checking its value. +### export function isMap +Check if the input is a Map object. @example isMap(new Map()) @returns true -### hasKeys -Check if an array of key exists in an object +```js [js] +isMap(new Map()) +``` + +### export function isEven +Check if the number is even. @example isEven(2) @returns true + +```js [js] +isEven(2) +``` + +### export function isOdd +Check if the number is odd. @example isOdd(3) @returns true + +```js [js] +isOdd(3) +``` + +### export function isPositive +Check if the number is positive. @example isPositive(1) @returns true + +```js [js] +isPositive(1) +``` + +### export function isNegative +Check if the number is negative. @example isNegative(-1) @returns true + +```js [js] +isNegative(-1) +``` + +### export function isZero +Check if the number is zero. @example isZero(0) @returns true + +```js [js] +isZero(0) +``` + +### export function isPrime +Check if the number is a prime number. @example isPrime(7) @returns true + +```js [js] +isPrime(7) +``` + +### export function isOptimusPrime +Check if the string is equal to "Optimus Prime". @example isOptimusPrime('Optimus Prime') @returns true + +```js [js] +isOptimusPrime('Optimus Prime') +``` + +### export function isPalindrome +Check if the string is a palindrome. @example isPalindrome('racecar') @returns true + +```js [js] +isPalindrome('racecar') +``` + +### export function isInteger +Check if the number is an integer. @example isInteger(1) @returns true + +```js [js] +isInteger(1) +``` + +### export function isFloat +Check if the number is a float. @example isFloat(1.5) @returns true + +```js [js] +isFloat(1.5) +``` + +### export function isBetween +Check if the number is between the specified range. @example isBetween(5, 1, 10) @returns true + +```js [js] +isBetween(5, 1, 10) +``` + +### export function isDivisibleBy +Check if the number is divisible by the specified number. @example isDivisibleBy(10, 2) @returns true + +```js [js] +isDivisibleBy(10, 2) +``` + +### export function isCreditCardNumber +Check if the input is a valid credit card number. @example isCreditCardNumber('4242424242424242') @returns true + +```js [js] +isCreditCardNumber('4242424242424242') +``` + +### export function isIPAddress +Check if the input is a valid IP address. @example isIPAddress('127.0.0.0') @returns true + +```js [js] +isIPAddress('127.0.0.0') +``` + +### export function isMACAddress +Check if the input is a valid MAC address. @example isMACAddress('00:00:00:00:00:00') @returns true + +```js [js] +isMACAddress('00:00:00:00:00:00') +``` + +### export function isLatLng +Check if the input is a valid latitude-longitude coordinate in the format lat,lng or lat,lng. @example isLatLng('40.741895,-73.989308') @returns true + +```js [js] +isLatLng('40.741895,-73.989308') +``` + +### export function isLatitude +Check if the input is a valid latitude coordinate. @example isLatitude('40.741895') @returns true + +```js [js] +isLatitude('40.741895') +``` + +### export function isLongitude +Check if the input is a valid longitude coordinate. @example isLongitude('-73.989308') @returns true + +```js [js] +isLongitude('-73.989308') +``` + +### export function isPort +Check if the input is a valid port number. @example isPort(3000) @returns true + +```js [js] +isPort(3000) +``` + +### export function isPresent +Checks if a property and value pair exists in an object. @example hasPropertyValue({ hello: 'world' }, 'hello', 'world') @returns true + +```js [js] +hasPropertyValue({ hello: 'world' }, 'hello', 'world') +``` + +### export function hasProperties +Check if a property exists in an object without checking its value. @example hasProperties({ hello: 'world' }, ['hello', 'world']) @returns true + +```js [js] +hasProperties({ hello: 'world' }, ['hello', 'world']) +``` + +### export function hasKeys +Check if an array of key exists in an object @example hasKeys({ hello: 'world' }, ['hello', 'world',]) @returns true + +```js [js] +hasKeys({ hello: 'world' }, ['hello', 'world',]) +``` diff --git a/docs.ts b/docs.ts index feb28071..eef268e9 100644 --- a/docs.ts +++ b/docs.ts @@ -1,84 +1,61 @@ -import * as fs from 'fs' -import * as path from 'path' +import { readFile, writeFile, readdir } from 'fs/promises' +import { resolve, extname, basename, join } from 'path' -// Define the directory path -const directoryPath = path.resolve('./utils/') +const directoryPath = resolve('./utils/') +const outputDirectory = resolve('./dist/') +const contentDirectory = resolve('./content/2.functions') -// Get a list of all files in the directory -const files = fs.readdirSync(directoryPath) +const functionPattern = /\/\*\*[\s\S]*?\*\/\s*(export\s+function\s+[a-zA-Z0-9_]+\([^)]*\)\s*:\s*[a-zA-Z]+\s*(?:{[\s\S]*?})?)?/gms +const metadataPattern = /\/\/\s+(title|description):\s+([^\r\n]*)/g +const subtitlePattern = /\/\/ (.+?)\/\/ <\/subtitle>/gs -// Filter the list to only include .ts files -const tsFiles = files.filter((file) => path.extname(file) === '.ts') +async function processFiles() { + try { + const tsFiles = (await readdir(directoryPath)).filter((file) => extname(file) === '.ts') + let combinedTsFile = '' -// Combine tsFiles into a single .ts file in /dist -let combinedTsFile = '' -tsFiles.forEach((tsFile) => { - const tsFilePath = path.resolve(directoryPath, tsFile) - const tsContent = fs.readFileSync(tsFilePath, 'utf-8') - combinedTsFile += tsContent + '\n' -}) -fs.writeFileSync(path.resolve('./dist/mods.ts'), combinedTsFile) + for (const tsFile of tsFiles) { + const tsContent = await readFile(resolve(directoryPath, tsFile), 'utf-8') + combinedTsFile += tsContent + '\n' -// Generate markdown documentation for each function -tsFiles.forEach((tsFile) => { - const tsFilePath = path.resolve(directoryPath, tsFile) - const tsContent = fs.readFileSync(tsFilePath, 'utf-8') - - // Improved pattern to match function declarations with JSDoc comments - const functionPattern = /\/\*\*[\s\S]*?\*\/\s*(export\s+function\s+[a-zA-Z0-9_]+\([^)]*\)\s*:\s*[a-zA-Z]+\s*{[\s\S]*?})/gm - const subtitlePattern = /\/\/ [\s\S]*?\/\/ <\/subtitle>/gm - - const functions = (tsContent.match(functionPattern) || []).map((match) => ({ match, type: 'function' })) - const subtitles = (tsContent.match(subtitlePattern) || []).map((match) => ({ match, type: 'subtitle' })) - const allMatches = [...functions, ...subtitles] + const markdownContent = generateMarkdown(tsContent) + await writeFile(join(contentDirectory, `${basename(tsFile, '.ts')}.md`), markdownContent) + console.log('Markdown documentation generated for:', tsFile) + } - let markdownContent = '' + await writeFile(join(outputDirectory, 'mods.ts'), combinedTsFile) + } catch (error) { + console.error('Error processing files:', error) + } +} - const pageTitleMatch = tsContent.match(/\/\/\s+title:\s+([^\r\n]*)/) - const pageDescriptionMatch = tsContent.match(/\/\/\s+description:\s+([^\r\n]*)/) +function generateMarkdown(tsContent: string): string { + const metadata = Object.fromEntries([...tsContent.matchAll(metadataPattern)].map((m) => [m[1], m[2]])) + let markdownContent = `# ${metadata.title || ''}\n\n#### ${metadata.description || ''}\n\n` - if (pageTitleMatch) markdownContent += `# ${pageTitleMatch[1]}\n\n` - if (pageDescriptionMatch) markdownContent += `#### ${pageDescriptionMatch[1]}\n\n` + const matches = [...tsContent.matchAll(functionPattern), ...tsContent.matchAll(subtitlePattern)] + matches.sort((a, b) => a.index! - b.index!) - allMatches.forEach((item) => { - if (item.type === 'subtitle') { - const subtitleMatch = /\/\/ (.+?)\/\/ <\/subtitle>/s.exec(item.match) - if (subtitleMatch) markdownContent += `## ${subtitleMatch[1].trim()}\n\n` + for (const match of matches) { + if (match[0].startsWith('// ')) { + markdownContent += `## ${match[1].trim()}\n\n` } else { - const functionNameMatch = /export function\s+([a-zA-Z0-9_]+)/.exec(item.match) - const functionName = functionNameMatch ? functionNameMatch[1] : '' - - const jsDocCommentMatch = /\/\*\*([\s\S]*?)\*\//.exec(item.match) - const jsDocComment = jsDocCommentMatch ? jsDocCommentMatch[1] : '' - - const description = jsDocComment + const [functionName] = /export function\s+([a-zA-Z0-9_]+)/.exec(match[0]) || [''] + const jsDoc = /\/\*\*([\s\S]*?)\*\//.exec(match[0])?.[1].trim() || '' + const description = jsDoc .split('\n') - .map((line) => - line - .trim() - .replace(/\/?\*+/g, '') - .trim() - ) + .map((line) => line.trim().replace(/\/?\*+/g, '')) .filter((line) => !line.startsWith('@')) .join(' ') - .replace(/\/$/, '') .trim() + const example = (jsDoc.match(/@example\s+([^\r\n]*)/) || [])[1] || '' - const example = (jsDocComment.match(/@example\s+([^\r\n]*)/) || [])[1] || '' - const returns = (jsDocComment.match(/@returns\s+([^\r\n]*)/) || [])[1] || '' - - markdownContent += `### ${functionName}\n` - markdownContent += `${description}\n\n` + markdownContent += `### ${functionName}\n${description}\n\n` if (example) markdownContent += '```js [js]\n' + example + '\n```\n\n' - if (example) markdownContent += '::example{:code=' + example + '}\n::\n\n' - // if (returns) markdownContent += '```html [example]\n' + returns + '\n```\n\n' } - }) - - markdownContent = markdownContent.replace(/\n\n\n/g, '\n\n') + } - const outputFilePath = path.resolve('./content/2.functions', `${path.basename(tsFile, '.ts')}.md`) - fs.writeFileSync(outputFilePath, markdownContent) + return markdownContent.replace(/\n\n\n/g, '\n\n') +} - console.log('Markdown documentation generated for:', tsFile, 'at:', outputFilePath) -}) +processFiles() diff --git a/utils/actions.ts b/utils/actions.ts index 38ba6155..a3c77001 100644 --- a/utils/actions.ts +++ b/utils/actions.ts @@ -1,14 +1,9 @@ // title: Actions // description: A collection of useful actions -// -// subtitle: Page Actions -// description: A collection of useful actions -// - /** - * Smoothly scroll to an anchor on the page - * @function scrollToAnchor('#my-anchor') + * Scrolls to the element with the specified ID. + * @example scrollToAnchor('#my-anchor') */ export function scrollToAnchor(id: string, callback?: () => void) { setTimeout(() => { @@ -26,7 +21,7 @@ export function scrollToAnchor(id: string, callback?: () => void) { /** * Smoothly scroll to the top of the page - * @function scrollToTop() + * @example scrollToTop() */ export function scrollToTop(callback?: () => void) { setTimeout(() => { @@ -43,7 +38,7 @@ export function scrollToTop(callback?: () => void) { /** * Smoothly scroll to the bottom of the page - * @function scrollToBottom() + * @example scrollToBottom() */ export function scrollToBottom(callback?: () => void) { setTimeout(() => { @@ -59,58 +54,48 @@ export function scrollToBottom(callback?: () => void) { } /** - * Toggles the body scroll - * @function toggleBodyScroll() + * Toggles the body scroll with the specified class name + * @example toggleBodyScroll('overflow-hidden') */ -export function toggleBodyScroll() { - document.body.classList.toggle('overflow-hidden') +export function toggleBodyScroll(className: string) { + document.body.classList.toggle(className) } /** * Toggles the element scroll - * @function toggleElementScroll(document.querySelector('#my-element')) + * @example toggleElementScroll(document.querySelector('#my-element')) */ -export function toggleElementScroll(element: HTMLElement) { - element.classList.toggle('overflow-hidden') +export function toggleElementScroll(element: HTMLElement, className: string) { + element.classList.toggle(className) } -// subtitle: Page Functions -// subtitledescription: A collection of useful actions - /** * Copies a text to the clipboard - * @function copyToClipboard() + * @example copyToClipboard() */ export function copyToClipboard(text: string, callback?: () => void) { navigator.clipboard .writeText(text) .then(() => { - if (callback) { - callback() - } + if (callback) callback() }) .catch((error) => { - if (callback) { - callback() - } + if (callback) callback() }) } /** * Toggles the fullscreen mode - * @function toggleFullScreen() + * @example toggleFullScreen() */ export function toggleFullScreen() { - if (document.fullscreenElement) { - document.exitFullscreen() - } else { - document.documentElement.requestFullscreen() - } + if (document.fullscreenElement) document.exitFullscreen() + else document.documentElement.requestFullscreen() } /** * Toggles the dark mode - * @function toggleDarkMode() + * @example toggleDarkMode() */ export function toggleDarkMode() { const prefersDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches @@ -119,20 +104,15 @@ export function toggleDarkMode() { /** * Redirects to a new URL - * @function redirect('https://example.com') + * @example redirect('https://example.com') */ export function redirect(url: string) { window.location.href = url } -// -// subtitle: Form Actions -// description: A collection of useful actions -// - /** * Resets a form - * @function resetForm(document.querySelector('form')) + * @example resetForm(document.querySelector('form')) */ export function resetForm(form: HTMLFormElement) { form.reset() @@ -140,7 +120,7 @@ export function resetForm(form: HTMLFormElement) { /** * Focuses on an element - * @function focusOn(document.querySelector('#my-element')) + * @example focusOn(document.querySelector('#my-element')) */ export function focusOn(element: HTMLElement) { element.focus() @@ -148,7 +128,7 @@ export function focusOn(element: HTMLElement) { /** * Focuses on the first element - * @function focusOnFirst(document.querySelector('#my-element')) + * @example focusOnFirst(document.querySelector('#my-element')) */ export function focusOnFirst(element: HTMLElement) { const input = element.querySelector('input') @@ -159,7 +139,7 @@ export function focusOnFirst(element: HTMLElement) { /** * Focuses on the last element - * @function focusOnLast(document.querySelector('#my-element')) + * @example focusOnLast(document.querySelector('#my-element')) */ export function focusOnLast(element: HTMLElement) { const inputs = element.querySelectorAll('input') @@ -171,7 +151,7 @@ export function focusOnLast(element: HTMLElement) { /** * Sets up a keyboard trap within an HTML element, allowing the focus to cycle between the first and last focusable elements when the Tab key is pressed. - * @function focusTrap(document.querySelector('#my-element')) + * @example focusTrap(document.querySelector('#my-element')) */ export function focusTrap(element: HTMLElement) { const focusableElements = element.querySelectorAll('a[href], button, textarea, input[type="text"], input[type="radio"], input[type="checkbox"], select') diff --git a/utils/detections.ts b/utils/detections.ts index aeedd4cd..a7ccc3de 100644 --- a/utils/detections.ts +++ b/utils/detections.ts @@ -3,7 +3,7 @@ /** * Detect the current device type (Mobile or Desktop) - * @function detectDevice() + * @example detectDevice() * @returns `Mobile` or `Desktop` */ export function detectDevice(): string { @@ -12,7 +12,7 @@ export function detectDevice(): string { /** * Detect the current operating system - * @function detectOS() + * @example detectOS() * @returns `Windows`, `Mac`, `Linux`, `UNIX`, or `Unknown` */ export function detectOS(): string { @@ -26,7 +26,7 @@ export function detectOS(): string { /** * Detects the user's browser based on the user agent string. - * @function detectBrowser() + * @example detectBrowser() * @returns `Chrome`, `Firefox`, `Safari`, `Opera`, `Edge`, `IE`, or `Unknown` */ export function detectBrowser(): string { @@ -35,7 +35,7 @@ export function detectBrowser(): string { /** * Detect if the browser window is currently active or hidden. - * @function detectActiveBrowser() + * @example detectActiveBrowser() */ export function detectActiveBrowser(): boolean { return !document.hidden @@ -43,7 +43,7 @@ export function detectActiveBrowser(): boolean { /** * Detect the current color scheme (Light or Dark) - * @function detectColorScheme() + * @example detectColorScheme() * @returns `Light` or `Dark` */ export function detectColorScheme(): string { @@ -52,7 +52,7 @@ export function detectColorScheme(): string { /** * Detect the current browser language - * @function detectBrowserLanguage() + * @example detectBrowserLanguage() */ export function detectBrowserLanguage(): string { return navigator.language @@ -60,7 +60,7 @@ export function detectBrowserLanguage(): string { /** * Detect the current user's location - * @function detectUserLocation() + * @example detectUserLocation() * @returns `US`, `UK`, `CA`, `AU`, `NZ`, `EU`, `Unknown` */ export function detectGeolocation(): Promise { @@ -71,7 +71,7 @@ export function detectGeolocation(): Promise { /** * Detect the current user's Timezone - * @function detectUserTimezone() + * @example detectUserTimezone() */ export function detectUserTimezone(): string { return Intl.DateTimeFormat().resolvedOptions().timeZone @@ -79,7 +79,7 @@ export function detectUserTimezone(): string { /** * Detect the currect device orientation - * @function detectDeviceOrientation() + * @example detectDeviceOrientation() */ export function detectDeviceOrientation(): string { return window.screen.orientation.type @@ -87,7 +87,7 @@ export function detectDeviceOrientation(): string { /** * Detect the current device motion - * @function detectDeviceMotion() + * @example detectDeviceMotion() */ export function detectDeviceMotion(): Promise { return new Promise((resolve, reject) => { @@ -98,7 +98,7 @@ export function detectDeviceMotion(): Promise { /** * Detect the browser's window size - * @function detectWindowSize() + * @example detectWindowSize() */ export function detectWindowSize(): { width: number; height: number } { return { @@ -109,7 +109,7 @@ export function detectWindowSize(): { width: number; height: number } { /** * Detect the screen or monitor size - * @function detectScreenSize() + * @example detectScreenSize() */ export function detectScreenSize(): { width: number; height: number } { return { @@ -120,7 +120,7 @@ export function detectScreenSize(): { width: number; height: number } { /** * Detect the container size via ID - * @function detectContainerSize('container') + * @example detectContainerSize('container') */ export function detectContainerSize(id: string): { width: number; height: number } { const element = document.getElementById(id) @@ -133,7 +133,7 @@ export function detectContainerSize(id: string): { width: number; height: number /** * Detect the current breakpoint based on Tailwind CSS breakpoints - * @function detectTailwindBreakpoint() + * @example detectTailwindBreakpoint() */ export function detectTailwindBreakpoint(): string { const width = window.innerWidth @@ -155,7 +155,7 @@ export function detectTailwindBreakpoint(): string { /** * Detect the current container breakpoint based on Tailwind CSS breakpoints - * @function detectTailwindContainerBreakpoint('container') + * @example detectTailwindContainerBreakpoint('container') */ export function detectTailwindContainerBreakpoint(id: string): string { const width = detectContainerSize(id).width @@ -189,7 +189,7 @@ export function detectTailwindContainerBreakpoint(id: string): string { /** * Detect the current scroll position of the window - * @function detectScrollPosition() + * @example detectScrollPosition() */ export function detectScrollPosition(): { x: number; y: number } { return { @@ -200,7 +200,7 @@ export function detectScrollPosition(): { x: number; y: number } { /** * Detect the current mouse position within the window - * @function detectMousePosition(event) + * @example detectMousePosition(event) */ export function detectMousePosition(event: MouseEvent) { return { @@ -211,7 +211,7 @@ export function detectMousePosition(event: MouseEvent) { /** * Detect the current mouse position within a container via ID - * @function detectRelativeMousePosition('container', event) + * @example detectRelativeMousePosition('container', event) */ export function detectRelativeMousePosition(id: string, e: MouseEvent) { const element = document.getElementById(id) @@ -225,7 +225,7 @@ export function detectRelativeMousePosition(id: string, e: MouseEvent) { /** * Detect the current network status of the user (Online or Offline) - * @function detectNetworkStatus() + * @example detectNetworkStatus() */ export function detectNetworkStatus(): string { return navigator.onLine ? 'Online' : 'Offline' @@ -233,7 +233,7 @@ export function detectNetworkStatus(): string { /** * Detect the current memory status of the user (RAM) - * @function detectMemoryStatus() + * @example detectMemoryStatus() */ export function detectMemoryStatus(): { totalJSHeapSize: number; usedJSHeapSize: number; jsHeapSizeLimit: number } { return { @@ -245,7 +245,7 @@ export function detectMemoryStatus(): { totalJSHeapSize: number; usedJSHeapSize: /** * Detect the current performance status of the user (CPU, RAM, etc.) - * @function detectPerformance() + * @example detectPerformance() */ export function detectPerformance(): Promise { return new Promise((resolve, reject) => { @@ -258,7 +258,7 @@ export function detectPerformance(): Promise { /** * Detect the current storage status of the user (Local Storage, Session Storage) - * @function detectStorage() + * @example detectStorage() */ export function detectStorage(): { localStorage: number; sessionStorage: number } { return { @@ -269,7 +269,7 @@ export function detectStorage(): { localStorage: number; sessionStorage: number /** * Returns a cookie value by name - * @function detectCookie('name') + * @example detectCookie('name') */ export function detectCookie(name: string) { const value = '; ' + document.cookie @@ -279,7 +279,7 @@ export function detectCookie(name: string) { /** * Returns a local storage value by name and parses it into JSON - * @function detectLocalStorage('name') + * @example detectLocalStorage('name') */ export function detectLocalStorage(name: string) { const item = localStorage.getItem(name) @@ -288,7 +288,7 @@ export function detectLocalStorage(name: string) { /** * Returns a session storage value by name and parses it into JSON - * @function detectSessionStorage('name') + * @example detectSessionStorage('name') */ export function detectSessionStorage(name: string) { const item = sessionStorage.getItem(name) @@ -297,7 +297,7 @@ export function detectSessionStorage(name: string) { /** * Returns a value from the URL by name - * @function detectURLParameters('http://url.com/page?name=Adam&surname=Smith') + * @example detectURLParameters('http://url.com/page?name=Adam&surname=Smith') */ export function detectURLParameters(url: string, param?: string) { const params = (url.match(/([^?=&]+)(=([^&]*))/g) || []).reduce((a: any, v: any) => ((a[v.slice(0, v.indexOf('='))] = v.slice(v.indexOf('=') + 1)), a), {}) @@ -311,7 +311,7 @@ export function detectURLParameters(url: string, param?: string) { /** * Returns a value from the URL hash by name - * @function detectURLHashParameters() + * @example detectURLHashParameters() */ export function detectURLHashParameters() { return detectURLParameters(window.location.hash) @@ -319,7 +319,7 @@ export function detectURLHashParameters() { /** * Retrieves and returns the parameters from the URL search query string - * @function detectURLSearchParameters() + * @example detectURLSearchParameters() */ export function detectURLSearchParameters() { return detectURLParameters(window.location.search) @@ -327,7 +327,7 @@ export function detectURLSearchParameters() { /** * Returns the current URL - * @function detectURL() + * @example detectURL() */ export function detectURL() { return window.location.href @@ -335,7 +335,7 @@ export function detectURL() { /** * Returns the current domain - * @function detectDomain() + * @example detectDomain() */ export function detectDomain() { return window.location.hostname @@ -343,7 +343,7 @@ export function detectDomain() { /** * Returns the current IP address - * @function detectIP() + * @example detectIP() */ export function detectIP() { return window.location.host @@ -351,7 +351,7 @@ export function detectIP() { /** * Returns the current port - * @function detectPort() + * @example detectPort() */ export function detectPort() { return window.location.port @@ -359,7 +359,7 @@ export function detectPort() { /** * Returns the current protocol (HTTP or HTTPS) - * @function detectProtocol() + * @example detectProtocol() */ export function detectProtocol() { return window.location.protocol @@ -367,7 +367,7 @@ export function detectProtocol() { /** * Returns the URL of the referring page (the page that linked to the current page) - * @function detectReferrer() + * @example detectReferrer() */ export function detectReferrer() { return document.referrer @@ -375,7 +375,7 @@ export function detectReferrer() { /** * Retrieves cached entries and optionally filters the entries based on a provided key - * @function detectCachedData('abc') + * @example detectCachedData('abc') */ export function detectCachedData(key?: string): PerformanceEntry[] { const cachedData = window.performance.getEntriesByType('resource') @@ -391,7 +391,7 @@ export function detectCachedData(key?: string): PerformanceEntry[] { /** * Detects if the element is currently in the viewport - * @function isInViewport(element) + * @example isInViewport(element) */ export function isInViewport(element: HTMLElement) { const rect = element.getBoundingClientRect() @@ -405,7 +405,7 @@ export function isInViewport(element: HTMLElement) { /** * Detects if the element is currently in the container via ID - * @function isInContainer(element, 'container') + * @example isInContainer(element, 'container') */ export function isInContainer(element: HTMLElement, id: string) { const rect = element.getBoundingClientRect() @@ -417,7 +417,7 @@ export function isInContainer(element: HTMLElement, id: string) { /** * Detects if the element is overflowing vertically - * @function isOverflowingY(element) + * @example isOverflowingY(element) */ export function isOverflowingY(element: HTMLElement) { return element.scrollWidth > element.clientWidth || element.scrollHeight > element.clientHeight @@ -425,7 +425,7 @@ export function isOverflowingY(element: HTMLElement) { /** * Detects if the element is overflowing horizontally - * @function isOverflowingX(element) + * @example isOverflowingX(element) */ export function isOverflowingX(element: HTMLElement) { return element.scrollWidth > element.clientWidth @@ -433,7 +433,7 @@ export function isOverflowingX(element: HTMLElement) { /** * Detects if the element is scrollable (overflowing vertically or horizontally) - * @function isScrollable(element) + * @example isScrollable(element) */ export function isScrollable(element: HTMLElement) { return isOverflowingY(element) || isOverflowingX(element) @@ -441,7 +441,7 @@ export function isScrollable(element: HTMLElement) { /** * Detects if the elements is an HTML element - * @function isElement(element) + * @example isElement(element) */ export function isElement(element: HTMLElement) { return element instanceof HTMLElement diff --git a/utils/generators.ts b/utils/generators.ts index c1e33d42..c785a8e5 100644 --- a/utils/generators.ts +++ b/utils/generators.ts @@ -3,7 +3,7 @@ /** * Generate a unique short ID based on the current timestamp - * @function generateShortId(36) + * @example generateShortId(36) * @returns 1HR2MIN3S */ export function generateShortId(length: number = 36): string { @@ -12,7 +12,7 @@ export function generateShortId(length: number = 36): string { /** * Generate initials from any string - * @function generateInitials('John Doe') + * @example generateInitials('John Doe') * @returns JD */ export function generateInitials(text: string, count: number = 2): string { diff --git a/utils/modifiers.ts b/utils/modifiers.ts index 54de0874..b5c1ce3c 100644 --- a/utils/modifiers.ts +++ b/utils/modifiers.ts @@ -3,7 +3,7 @@ /** * Adds a space between the last two words in a string. - * @function widont('Cool cool cool') + * @example widont('Cool cool cool') * @returns cool cool cool */ export function widont(text: string): string { @@ -14,7 +14,7 @@ export function widont(text: string): string { /** * Strip HTML tags from a string. - * @function stripHtml('

    Hello World

    ') + * @example stripHtml('

    Hello World

    ') * @returns Hello World */ export function stripHtml(text: string): string { @@ -23,7 +23,7 @@ export function stripHtml(text: string): string { /** * Escape HTML entities in a string. - * @function escapeHtml('

    Hello World

    ') + * @example escapeHtml('

    Hello World

    ') * @returns <p>Hello World</p> */ export function escapeHtml(text: string): string { @@ -32,7 +32,7 @@ export function escapeHtml(text: string): string { /** * Unescape HTML entities in a string. - * @function unescapeHtml('<p>Hello World</p>') + * @example unescapeHtml('<p>Hello World</p>') * @returns

    Hello World

    */ export function unescapeHtml(text: string): string { @@ -41,7 +41,7 @@ export function unescapeHtml(text: string): string { /** * Strip HTML tags from a string. - * @function stripTags('

    Hello World

    ') + * @example stripTags('

    Hello World

    ') * @returns Hello World */ export function stripTags(text: string): string { @@ -50,7 +50,7 @@ export function stripTags(text: string): string { /** * Converts a string to-a-slug. - * @function slugify('Hello World') + * @example slugify('Hello World') * @returns hello-world */ export function slugify(text: string): string { @@ -62,7 +62,7 @@ export function slugify(text: string): string { /** * Converts a slug to a string. - * @function deslugify('hello-world') + * @example deslugify('hello-world') * @returns hello world */ export function deslugify(text: string): string { @@ -71,7 +71,7 @@ export function deslugify(text: string): string { /** * Truncates a string to a specified length of characters. - * @function truncate('Hello World', 5) + * @example truncate('Hello World', 5) * @returns Hello... */ export function truncate(text: string, length: number): string { @@ -83,7 +83,7 @@ export function truncate(text: string, length: number): string { /** * Truncates a string by a number of words - * @function truncateWords('Hello World', 1) + * @example truncateWords('Hello World', 1) * @returns Hello... */ export function truncateWords(text: string, length: number): string { @@ -98,7 +98,7 @@ export function truncateWords(text: string, length: number): string { /** * Counts the number of words in a string. - * @function countWords('Hello World') + * @example countWords('Hello World') * @returns 2 */ export function countWords(text: string): number { @@ -107,7 +107,7 @@ export function countWords(text: string): number { /** * Counts the number of characters in a string. - * @function countCharacters('Hello World') + * @example countCharacters('Hello World') * @returns 11 */ export function countCharacters(text: string): number { @@ -116,7 +116,7 @@ export function countCharacters(text: string): number { /** * Counts the number of lines in a string. - * @function countLines('Hello World') + * @example countLines('Hello World') * @returns 1 */ export function countLines(text: string): number { @@ -125,7 +125,7 @@ export function countLines(text: string): number { /** * Strips whitespace from a string. - * @function stripWhitespace('Hello World') + * @example stripWhitespace('Hello World') * @returns HelloWorld */ export function stripWhitespace(text: string): string { @@ -134,7 +134,7 @@ export function stripWhitespace(text: string): string { /** * Strips numbers from a string. - * @function stripNumbers('Hello World 123') + * @example stripNumbers('Hello World 123') * @returns Hello World */ export function stripNumbers(text: string): string { @@ -143,7 +143,7 @@ export function stripNumbers(text: string): string { /** * Strips punctuation from a string. - * @function stripPunctuation('Hello World!') + * @example stripPunctuation('Hello World!') * @returns Hello World */ export function stripPunctuation(text: string): string { @@ -152,7 +152,7 @@ export function stripPunctuation(text: string): string { /** * Strips symbols from a string. - * @function stripSymbols('Hello World!') + * @example stripSymbols('Hello World!') * @returns Hello World */ export function stripSymbols(text: string): string { @@ -161,7 +161,7 @@ export function stripSymbols(text: string): string { /** * Strips emojis from a string (requires ES6 Unicode support) 🦊. - * @function stripEmojis('Hello World! 🦊') + * @example stripEmojis('Hello World! 🦊') * @returns Hello World! */ export function stripEmojis(text: string): string { @@ -170,7 +170,7 @@ export function stripEmojis(text: string): string { /** * Returns the reading time of a string in Hours, Minutes, and Seconds. - * @function readingTime('Once, in a vibrant online forum, lived Mod Max, guardian of digital harmony. Max cherished his old scooter, Swift, a symbol of freedom. Navigating both virtual and real worlds, they became legends. Trolls quivered, posts flourished, and lanes whizzed by. Swift’s wheels spun tales, and Max’s keys kept peace. Together, they discovered uncharted threads and hidden lanes. Their journey, an endless adventure, painted pixels and pavements with stories of unity and exhilaration, leaving a trail for all in the intertwined realms of screens and streets.') + * @example readingTime('Once, in a vibrant online forum, lived Mod Max, guardian of digital harmony. Max cherished his old scooter, Swift, a symbol of freedom. Navigating both virtual and real worlds, they became legends. Trolls quivered, posts flourished, and lanes whizzed by. Swift’s wheels spun tales, and Max’s keys kept peace. Together, they discovered uncharted threads and hidden lanes. Their journey, an endless adventure, painted pixels and pavements with stories of unity and exhilaration, leaving a trail for all in the intertwined realms of screens and streets.') * @returns 1 minute */ export function readingTime(text: string, wordsPerMinute = 200): string { @@ -183,7 +183,7 @@ export function readingTime(text: string, wordsPerMinute = 200): string { /** * Adds plurals to a string. - * @function pluralize('scooter', 10) + * @example pluralize('scooter', 10) * @returns scooters */ export function pluralize(text: string, count: number): string { @@ -196,7 +196,7 @@ export function pluralize(text: string, count: number): string { /** * Removes plurals from a string. - * @function singularize('scooters') + * @example singularize('scooters') * @returns scooter */ export function singularize(text: string): string { @@ -209,7 +209,7 @@ export function singularize(text: string): string { /** * Converts a number to a string with ordinal suffix. - * @function ordinalize(1) + * @example ordinalize(1) * @returns 1st */ export function ordinalize(number: number): string { @@ -221,7 +221,7 @@ export function ordinalize(number: number): string { /** * Replaces underscores with spaces and capitalizes the first letter of each word. - * @function humanize('hello_world') + * @example humanize('hello_world') * @returns Hello World */ export function humanize(text: string): string { @@ -233,7 +233,7 @@ export function humanize(text: string): string { /** * Removes spaces and capitalizes the first letter of each word except for the first word. - * @function camelCase('hello world') + * @example camelCase('hello world') * @returns helloWorld */ export function camelCase(text: string): string { @@ -246,7 +246,7 @@ export function camelCase(text: string): string { /** * Removes spaces and capitalizes the first letter of each word. - * @function pascalCase('hello world') + * @example pascalCase('hello world') * @returns HelloWorld */ export function pascalCase(text: string): string { @@ -259,7 +259,7 @@ export function pascalCase(text: string): string { /** * Replaces spaces with underscores and converts to lowercase. - * @function snakeCase('hello world') + * @example snakeCase('hello world') * @returns hello_world */ export function snakeCase(text: string): string { @@ -272,7 +272,7 @@ export function snakeCase(text: string): string { /** * Replaces spaces with hyphens and converts to lowercase. - * @function titleize('Hello World') + * @example titleize('Hello World') * @returns hello-world */ export function kebabCase(text: string): string { @@ -285,7 +285,7 @@ export function kebabCase(text: string): string { /** * Converts to title case by capitalizing the first letter of each word. - * @function titleCase('hello world') + * @example titleCase('hello world') * @returns Hello World */ export function titleCase(text: string): string { @@ -298,7 +298,7 @@ export function titleCase(text: string): string { /** * Converts to sentence case by capitalizing the first letter of the first word. - * @function sentenceCase('hello world') + * @example sentenceCase('hello world') * @returns Hello world */ export function sentenceCase(text: string): string { @@ -311,7 +311,7 @@ export function sentenceCase(text: string): string { /** * Adds a prefix to a string if it doesn't already start with the prefix. - * @function startWith('usemods.com', 'https://') + * @example startWith('usemods.com', 'https://') * @returns https://usemods.com */ export function startWith(text: string, start: string): string { @@ -324,7 +324,7 @@ export function startWith(text: string, start: string): string { /** * Removes a prefix from a string if it starts with the prefix. - * @function startWithout('https://usemods.com', 'https://') + * @example startWithout('https://usemods.com', 'https://') * @returns usemods.com */ @@ -338,7 +338,7 @@ export function startWithout(start: string, text: string): string { /** * Adds a suffix to a string if it doesn't already end with the suffix. - * @function endWith('https://usemods', '.com') + * @example endWith('https://usemods', '.com') * @returns https://usemods.com */ export function endWith(text: string, end: string): string { @@ -351,7 +351,7 @@ export function endWith(text: string, end: string): string { /** * Removes a suffix from a string if it ends with the suffix. - * @function endWithout('https://usemods.com.au', '.au') + * @example endWithout('https://usemods.com.au', '.au') * @returns https://usemods.com */ export function endWithout(text: string, end: string): string { @@ -367,7 +367,7 @@ export function endWithout(text: string, end: string): string { * @param text - The string to surround. * @param prefix - The prefix to add. * @param suffix - The suffix to add. - * @function surround('https://', 'usemods', '.com') + * @example surround('https://', 'usemods', '.com') * @returns https://usemods.com */ export function surround(start: string, text: string, end: string): string { @@ -389,7 +389,7 @@ export function surround(start: string, text: string, end: string): string { /** * Converts a string to title case following the Chicago Manual of Style rules. * @reference https://www.chicagomanualofstyle.org/book/ed17/frontmatter/toc.html - * @function title('the quick brown fox jumps over the lazy dog') + * @example title('the quick brown fox jumps over the lazy dog') * @returns The Quick Brown Fox Jumps over the Lazy Dog */ export function title(text: string): string { @@ -441,7 +441,7 @@ export function title(text: string): string { /** * Wraps each word in a string with a span tag. - * @function splitByWords('Hello World. How are you?') + * @example splitByWords('Hello World. How are you?') * @returns Hello world. How are you? */ export function splitByWords(text: string): string { @@ -473,7 +473,7 @@ export function splitByWords(text: string): string { /** * Creates an array of list items (`
  • `) from an array of strings. - * @function list(['one', 'two', 'three']) + * @example list(['one', 'two', 'three']) * @returns */ export function list(items: any[], listType: string = 'ul'): string { @@ -494,7 +494,7 @@ export function list(items: any[], listType: string = 'ul'): string { /** * Shuffles an array. - * @function shuffle(['one', 'two', 'three']) + * @example shuffle(['one', 'two', 'three']) * @returns ['three', 'one', 'two'] */ export function shuffle(items: any[]): any[] { @@ -505,7 +505,7 @@ export function shuffle(items: any[]): any[] { * Returns unique array values with an optional property to pluck. * @param items - The array of items. * @param property - The property to pluck (optional). - * @function unique(['one', 'two', 'three', 'one']) + * @example unique(['one', 'two', 'three', 'one']) * @returns ['one', 'two', 'three'] */ export function unique(property: string | null = null, ...arrays: (string | { [key: string]: any })[][]): any[] { @@ -530,7 +530,7 @@ export function unique(property: string | null = null, ...arrays: (string | { [k /** * Returns the difference between two arrays. - * @function difference(['one', 'two', 'three'], ['one', 'two']) + * @example difference(['one', 'two', 'three'], ['one', 'two']) * @returns ['three'] */ export function difference(...arrays: any[][]): any[] { @@ -540,7 +540,7 @@ export function difference(...arrays: any[][]): any[] { /** * Returns the first item in an array. - * @function first(['one', 'two', 'three']) + * @example first(['one', 'two', 'three']) * @returns one */ export function first(items: any[]): string { @@ -549,7 +549,7 @@ export function first(items: any[]): string { /** * Returns the last item in an array. - * @function last(['one', 'two', 'three']) + * @example last(['one', 'two', 'three']) * @returns three */ export function last(items: any[]): string { @@ -558,7 +558,7 @@ export function last(items: any[]): string { /** * Returns the nth item in an array. - * @function nth(['one', 'two', 'three'], 1) + * @example nth(['one', 'two', 'three'], 1) * @returns two */ export function nth(items: any[], nth: number): string { @@ -567,7 +567,7 @@ export function nth(items: any[], nth: number): string { /** * Offset the first item in an array. - * @function offset(['one', 'two', 'three'], 1) + * @example offset(['one', 'two', 'three'], 1) * @returns ['two', 'three'] */ export function offset(items: any[], offset: number): any[] { @@ -576,7 +576,7 @@ export function offset(items: any[], offset: number): any[] { /** * Groups an array of objects by a property. - * @function group([{ name: 'one' }, { name: 'two' }, { name: 'one' }], 'name') + * @example group([{ name: 'one' }, { name: 'two' }, { name: 'one' }], 'name') * @returns { one: [{ name: 'one' }, { name: 'one' }], two: [{ name: 'two' }] } */ export function group(items: { [key: string]: any }[], property: string): { [key: string]: any } { @@ -592,7 +592,7 @@ export function group(items: { [key: string]: any }[], property: string): { [key /** * Chunks an array into sections of a specified size. - * @function chunk(['one', 'two', 'three', 'four', 'five'], 2) + * @example chunk(['one', 'two', 'three', 'four', 'five'], 2) * @returns [['one', 'two'], ['three', 'four'], ['five']] */ export function groupBy(items: any[], size: number): any[][] { @@ -605,7 +605,7 @@ export function groupBy(items: any[], size: number): any[][] { /** * Flatten an array of arrays. - * @function flatten([['one', 'two'], ['three', 'four'], ['five']]) + * @example flatten([['one', 'two'], ['three', 'four'], ['five']]) * @returns ['one', 'two', 'three', 'four', 'five'] */ export function flatten(items: any[]): any[] { @@ -620,7 +620,7 @@ export function flatten(items: any[]): any[] { /** * Returns an array with a filtered out property. - * @function without([{ name: 'one', food: 'apple' }, { name: 'two', food: 'grape' }, { name: 'one', food: 'pear' }], 'name') + * @example without([{ name: 'one', food: 'apple' }, { name: 'two', food: 'grape' }, { name: 'one', food: 'pear' }], 'name') * @returns [{ food: 'apple' }, { food: 'grape' }, { food: 'pear' }] */ @@ -644,7 +644,7 @@ export function without(items: any[], properties: any | any[]): any[] { /** * Combine two or more arrays - * @function combine(['one', 'two'], ['three', 'four'], ['five']) + * @example combine(['one', 'two'], ['three', 'four'], ['five']) * @returns ['one', 'two', 'three', 'four', 'five'] */ export function combine(...arrays: any[][]): any[] { @@ -653,7 +653,7 @@ export function combine(...arrays: any[][]): any[] { /** * Combine two or more unique arrays - * @function combineUnique(['one', 'two'], ['three', 'four', 'two'], ['five', 'one']) + * @example combineUnique(['one', 'two'], ['three', 'four', 'two'], ['five', 'one']) * @returns ['one', 'two', 'three', 'four', 'five'] */ export function combineUnique(...items: (any | any[])[]): any[] { @@ -672,7 +672,7 @@ export function combineUnique(...items: (any | any[])[]): any[] { /** * Combine two or more arrays or objects without a property. - * @function combineWithout({ id: 1, name: 'A' }, { id: 2, name: 'B' }, { id: 3, name: 'C' }, 'id') + * @example combineWithout({ id: 1, name: 'A' }, { id: 2, name: 'B' }, { id: 3, name: 'C' }, 'id') * @returns [1, 2, 3] */ export function combineWithout( @@ -695,7 +695,7 @@ export function combineWithout( /** * Reverse an array. - * @function reverse(['one', 'two', 'three']) + * @example reverse(['one', 'two', 'three']) * @returns ['three', 'two', 'one'] */ export function reverse(items: any[]): any[] { @@ -704,7 +704,7 @@ export function reverse(items: any[]): any[] { /** * Sort an array by a property. - * @function sortBy([{ name: 'John', age: 25 },{ name: 'Jane', age: 30 },{ name: 'Jill', age: 20 }], 'age') + * @example sortBy([{ name: 'John', age: 25 },{ name: 'Jane', age: 30 },{ name: 'Jill', age: 20 }], 'age') * @returns [{ name: 'Jill', age: 20 },{ name: 'John', age: 25 },{ name: 'Jane', age: 30 }] */ export function sortBy(items: { [key: string]: any }[], property: string): { [key: string]: any }[] { diff --git a/utils/numbers.ts b/utils/numbers.ts index b5562499..66eb3c57 100644 --- a/utils/numbers.ts +++ b/utils/numbers.ts @@ -3,7 +3,7 @@ /** * Generates a random integer between the specified minimum and maximum values. - * @function random(1, 10) + * @example random(1, 10) * @returns 5 */ export function random(min: number, max: number): number { @@ -12,7 +12,7 @@ export function random(min: number, max: number): number { /** * Calculates the sum of an array of numbers. - * @function sum([1, 2, 3]) + * @example sum([1, 2, 3]) * @returns 6 */ export function sum(numbers: number[]): number { @@ -21,7 +21,7 @@ export function sum(numbers: number[]): number { /** * Calculates the mean of an array of numbers. - * @function average([1, 2, 3]) + * @example average([1, 2, 3]) * @returns 2 */ export function mean(numbers: number[]): number { @@ -30,7 +30,7 @@ export function mean(numbers: number[]): number { /** * Calculates the mean of an array of numbers. - * @function average([1, 2, 3]) + * @example average([1, 2, 3]) * @returns 2 */ export function average(numbers: number[]): number { @@ -39,7 +39,7 @@ export function average(numbers: number[]): number { /** * Calculates the median of an array of numbers. - * @function median([1, 2, 3]) + * @example median([1, 2, 3]) * @returns 2 */ export function median(numbers: number[]): number { @@ -55,7 +55,7 @@ export function median(numbers: number[]): number { /** * Calculates the mode of an array of numbers. - * @function mode([1, 2, 2, 3]) + * @example mode([1, 2, 2, 3]) * @returns 2 */ export function mode(numbers: number[]): number | null { @@ -76,7 +76,7 @@ export function mode(numbers: number[]): number | null { /** * Finds the minimum value in an array of numbers. - * @function min([1, 2, 3]) + * @example min([1, 2, 3]) * @returns 1 */ export function min(numbers: number[]): number { @@ -85,7 +85,7 @@ export function min(numbers: number[]): number { /** * Finds the maximum value in an array of numbers. - * @function max([1, 2, 3]) + * @example max([1, 2, 3]) * @returns 3 */ export function max(numbers: number[]): number { @@ -94,7 +94,7 @@ export function max(numbers: number[]): number { /** * Clamps a number between the specified minimum and maximum values. - * @function clamp(1, 10, 20) + * @example clamp(1, 10, 20) * @returns 10 */ export function clamp(number: number, min: number, max: number): number { @@ -103,7 +103,7 @@ export function clamp(number: number, min: number, max: number): number { /** * Returns the minimum and maximum values in an array of numbers. - * @function minMax([1, 2, 3, 4, 5]) + * @example minMax([1, 2, 3, 4, 5]) * @returns [1, 5] */ export function minMax(numbers: number[]): [number, number] { @@ -112,7 +112,7 @@ export function minMax(numbers: number[]): [number, number] { /** * Returns the difference between two values, expressed as a positive number. - * @function range(-10, -20) + * @example range(-10, -20) * @returns 10 */ export function range(a: number, b: number): number { @@ -121,7 +121,7 @@ export function range(a: number, b: number): number { /** * Returns the difference between two values, as a percentage. - * @function differenceAsPercentage(10, 20) + * @example differenceAsPercentage(10, 20) * @returns 100 */ export function rangeAsPercentage(a: number, b: number, decimals: number | null = null): number { @@ -131,7 +131,7 @@ export function rangeAsPercentage(a: number, b: number, decimals: number | null /** * Returns the percentage of a value, relative to another value. - * @function percentage(10, 100) + * @example percentage(10, 100) * @returns 10 */ export function percentage(value: number, total: number): number { @@ -140,7 +140,7 @@ export function percentage(value: number, total: number): number { /** * Returns the standard deviation of an array of numbers. - * @function standardDeviation([1, 2, 3, 20, 120, 2000]) + * @example standardDeviation([1, 2, 3, 20, 120, 2000]) * @returns 0.5 */ export function standardDeviation(numbers: number[]): number { @@ -152,7 +152,7 @@ export function standardDeviation(numbers: number[]): number { /** * Returns the measure of asymmetry of the probability distribution of an array of numbers. * The skewness value can be positive, zero, negative, or undefined. - * @function skewness([1, 2, 3, 20, 120, 2000]) + * @example skewness([1, 2, 3, 20, 120, 2000]) * @returns 2.5 */ export function skewness(numbers: number[]): number { @@ -165,7 +165,7 @@ export function skewness(numbers: number[]): number { /** * Return the frequency of all values (numbers, string or boolean) in an array as an object - * @function frequency([1, 3, 2, 3, 3, 3, 'a', 'b', 'c', 'c']) + * @example frequency([1, 3, 2, 3, 3, 3, 'a', 'b', 'c', 'c']) * @returns { '1': 1, '2': 1, '3': 4, a: 1, b: 1, c: 2 } */ export function frequency(array: (number | string)[]): Record { @@ -177,7 +177,7 @@ export function frequency(array: (number | string)[]): Record { /** * Returns the fequency of a property value in an array - * @function frequencyOfPropert([1, 3, 2, 3, 3, 3, 'a', 'b', 'c', 'c'], 3) + * @example frequencyOfPropert([1, 3, 2, 3, 3, 3, 'a', 'b', 'c', 'c'], 3) * @returns 4 */ export function frequencyOfProperty(array: (number | string)[], property: number | string): number { diff --git a/utils/validators.ts b/utils/validators.ts index 13c61753..c840a829 100644 --- a/utils/validators.ts +++ b/utils/validators.ts @@ -3,7 +3,7 @@ /** * Check if the input is a valid email address. - * @function isEmail('hello@usemods.com') + * @example isEmail('hello@usemods.com') * @returns true */ export function isEmail(email: string): boolean { @@ -13,7 +13,7 @@ export function isEmail(email: string): boolean { /** * Check if the input is a valid number. - * @function isNumber('123') + * @example isNumber('123') * @returns true */ export function isNumber(value: string | number): boolean { @@ -23,7 +23,7 @@ export function isNumber(value: string | number): boolean { /** * Check if the input is a valid URL. - * @function isURL('https://usemods.com') + * @example isURL('https://usemods.com') * @returns true */ export function isURL(url: string): boolean { @@ -33,7 +33,7 @@ export function isURL(url: string): boolean { /** * Check if the input is a valid UUID. - * @function isUUID('c9bf9e57-1685-4c89-bafb-ff5af830be8a') + * @example isUUID('c9bf9e57-1685-4c89-bafb-ff5af830be8a') * @returns true */ export function isUUID(uuid: string): boolean { @@ -43,7 +43,7 @@ export function isUUID(uuid: string): boolean { /** * Check if the input is a valid JSON string. - * @function isJSON('{"hello": "world"}') + * @example isJSON('{"hello": "world"}') * @returns true */ export function isJSON(json: string): boolean { @@ -57,7 +57,7 @@ export function isJSON(json: string): boolean { /** * Check if the input is a valid hexadecimal color code. - * @function isHex('#fff') + * @example isHex('#fff') * @returns true */ export function isHex(hex: string): boolean { @@ -67,7 +67,7 @@ export function isHex(hex: string): boolean { /** * Check if the input is an empty string. - * @function isEmpty('') + * @example isEmpty('') * @returns true */ export function isEmpty(text: string): boolean { @@ -76,7 +76,7 @@ export function isEmpty(text: string): boolean { /** * Check if the input contains only alphabetic characters. - * @function isAlpha('hello') + * @example isAlpha('hello') * @returns true */ export function isAlpha(text: string): boolean { @@ -86,7 +86,7 @@ export function isAlpha(text: string): boolean { /** * Check if the input contains only alphanumeric characters. - * @function isAlphanumeric('hello123') + * @example isAlphanumeric('hello123') * @returns true */ export function isAlphanumeric(text: string): boolean { @@ -96,7 +96,7 @@ export function isAlphanumeric(text: string): boolean { /** * Check if the input is an array. - * @function isArray([1, 2, 3]) + * @example isArray([1, 2, 3]) * @returns true */ export function isArray(array: any): boolean { @@ -105,7 +105,7 @@ export function isArray(array: any): boolean { /** * Check if the input is an object. - * @function isObject({ hello: 'world' }) + * @example isObject({ hello: 'world' }) * @returns true */ export function isObject(value: any): boolean { @@ -114,7 +114,7 @@ export function isObject(value: any): boolean { /** * Check if the input is a boolean value. - * @function isBoolean(true) + * @example isBoolean(true) * @returns true */ export function isBoolean(boolean: any): boolean { @@ -123,7 +123,7 @@ export function isBoolean(boolean: any): boolean { /** * Check if the input is a function. - * @function isFunction(() => {}) + * @example isFunction(() => {}) * @returns true */ export function isFunction(functionToCheck: any): boolean { @@ -132,7 +132,7 @@ export function isFunction(functionToCheck: any): boolean { /** * Check if the input is undefined. - * @function isUndefined(undefined) + * @example isUndefined(undefined) * @returns true */ export function isUndefined(value: any): boolean { @@ -141,7 +141,7 @@ export function isUndefined(value: any): boolean { /** * Check if the input is null. - * @function isNull(null) + * @example isNull(null) * @returns true */ export function isNull(value: any): boolean { @@ -150,7 +150,7 @@ export function isNull(value: any): boolean { /** * Check if the input is a valid Date object. - * @function isDate(new Date()) + * @example isDate(new Date()) * @returns true */ export function isDate(date: any): boolean { @@ -159,7 +159,7 @@ export function isDate(date: any): boolean { /** * Check if the input is an Error object with a defined message. - * @function isError(new Error('hello')) + * @example isError(new Error('hello')) * @returns true */ export function isError(error: any): boolean { @@ -168,7 +168,7 @@ export function isError(error: any): boolean { /** * Check if the input is a valid time in HH:mm format. - * @function isTime('12:00') + * @example isTime('12:00') * @returns true */ export function isTime(time: any): boolean { @@ -178,7 +178,7 @@ export function isTime(time: any): boolean { /** * Check if the input year is a leap year. - * @function isLeapYear(2020) + * @example isLeapYear(2020) * @returns true */ export function isLeapYear(year: number): boolean { @@ -187,7 +187,7 @@ export function isLeapYear(year: number): boolean { /** * Check if the input is a Promise object. - * @function isPromise(new Promise(() => {})) + * @example isPromise(new Promise(() => {})) * @returns true */ export function isPromise(promise: any): boolean { @@ -196,7 +196,7 @@ export function isPromise(promise: any): boolean { /** * Check if the input is a Set object. - * @function isSet(new Set()) + * @example isSet(new Set()) * @returns true */ export function isSet(set: any): boolean { @@ -205,7 +205,7 @@ export function isSet(set: any): boolean { /** * Check if the input is a Map object. - * @function isMap(new Map()) + * @example isMap(new Map()) * @returns true */ export function isMap(map: any): boolean { @@ -214,7 +214,7 @@ export function isMap(map: any): boolean { /** * Check if the number is even. - * @function isEven(2) + * @example isEven(2) * @returns true */ export function isEven(number: any): boolean { @@ -223,7 +223,7 @@ export function isEven(number: any): boolean { /** * Check if the number is odd. - * @function isOdd(3) + * @example isOdd(3) * @returns true */ export function isOdd(number: any): boolean { @@ -232,7 +232,7 @@ export function isOdd(number: any): boolean { /** * Check if the number is positive. - * @function isPositive(1) + * @example isPositive(1) * @returns true */ export function isPositive(number: any): boolean { @@ -241,7 +241,7 @@ export function isPositive(number: any): boolean { /** * Check if the number is negative. - * @function isNegative(-1) + * @example isNegative(-1) * @returns true */ export function isNegative(number: any): boolean { @@ -250,7 +250,7 @@ export function isNegative(number: any): boolean { /** * Check if the number is zero. - * @function isZero(0) + * @example isZero(0) * @returns true */ export function isZero(number: any): boolean { @@ -259,7 +259,7 @@ export function isZero(number: any): boolean { /** * Check if the number is a prime number. - * @function isPrime(7) + * @example isPrime(7) * @returns true */ export function isPrime(number: any): boolean { @@ -272,7 +272,7 @@ export function isPrime(number: any): boolean { /** * Check if the string is equal to "Optimus Prime". - * @function isOptimusPrime('Optimus Prime') + * @example isOptimusPrime('Optimus Prime') * @returns true */ export function isOptimusPrime(text: string): boolean { @@ -281,7 +281,7 @@ export function isOptimusPrime(text: string): boolean { /** * Check if the string is a palindrome. - * @function isPalindrome('racecar') + * @example isPalindrome('racecar') * @returns true */ export function isPalindrome(text: any): boolean { @@ -293,7 +293,7 @@ export function isPalindrome(text: any): boolean { /** * Check if the number is an integer. - * @function isInteger(1) + * @example isInteger(1) * @returns true */ export function isInteger(number: number): boolean { @@ -302,7 +302,7 @@ export function isInteger(number: number): boolean { /** * Check if the number is a float. - * @function isFloat(1.5) + * @example isFloat(1.5) * @returns true */ export function isFloat(number: number): boolean { @@ -311,7 +311,7 @@ export function isFloat(number: number): boolean { /** * Check if the number is between the specified range. - * @function isBetween(5, 1, 10) + * @example isBetween(5, 1, 10) * @returns true */ export function isBetween(number: number, min: number, max: number): boolean { @@ -323,7 +323,7 @@ export function isBetween(number: number, min: number, max: number): boolean { /** * Check if the number is divisible by the specified number. - * @function isDivisibleBy(10, 2) + * @example isDivisibleBy(10, 2) * @returns true */ export function isDivisibleBy(number: number, divisor: number): boolean { @@ -332,7 +332,7 @@ export function isDivisibleBy(number: number, divisor: number): boolean { /** * Check if the input is a valid credit card number. - * @function isCreditCardNumber('4242424242424242') + * @example isCreditCardNumber('4242424242424242') * @returns true */ export function isCreditCardNumber(number: string): boolean { @@ -342,7 +342,7 @@ export function isCreditCardNumber(number: string): boolean { /** * Check if the input is a valid IP address. - * @function isIPAddress('127.0.0.0') + * @example isIPAddress('127.0.0.0') * @returns true */ export function isIPAddress(ip: string): boolean { @@ -352,7 +352,7 @@ export function isIPAddress(ip: string): boolean { /** * Check if the input is a valid MAC address. - * @function isMACAddress('00:00:00:00:00:00') + * @example isMACAddress('00:00:00:00:00:00') * @returns true */ export function isMACAddress(mac: string): boolean { @@ -362,7 +362,7 @@ export function isMACAddress(mac: string): boolean { /** * Check if the input is a valid latitude-longitude coordinate in the format lat,lng or lat,lng. - * @function isLatLng('40.741895,-73.989308') + * @example isLatLng('40.741895,-73.989308') * @returns true */ export function isLatLng(latLng: string): boolean { @@ -371,7 +371,7 @@ export function isLatLng(latLng: string): boolean { } /** * Check if the input is a valid latitude coordinate. - * @function isLatitude('40.741895') + * @example isLatitude('40.741895') * @returns true */ export function isLatitude(latitude: string): boolean { @@ -381,7 +381,7 @@ export function isLatitude(latitude: string): boolean { /** * Check if the input is a valid longitude coordinate. - * @function isLongitude('-73.989308') + * @example isLongitude('-73.989308') * @returns true */ export function isLongitude(longitude: string): boolean { @@ -391,7 +391,7 @@ export function isLongitude(longitude: string): boolean { /** * Check if the input is a valid port number. - * @function isPort(3000) + * @example isPort(3000) * @returns true */ export function isPort(port: number): boolean { @@ -400,7 +400,7 @@ export function isPort(port: number): boolean { /** * Checks if a property and value pair exists in an object. - * @function hasPropertyValue({ hello: 'world' }, 'hello', 'world') + * @example hasPropertyValue({ hello: 'world' }, 'hello', 'world') * @returns true */ export function isPresent(object: any, property: string, value: any): boolean { @@ -409,7 +409,7 @@ export function isPresent(object: any, property: string, value: any): boolean { /** * Check if a property exists in an object without checking its value. - * @function hasProperties({ hello: 'world' }, ['hello', 'world']) + * @example hasProperties({ hello: 'world' }, ['hello', 'world']) * @returns true */ export function hasProperties(object: any, properties: string[], strict: boolean = true): boolean { @@ -424,7 +424,7 @@ export function hasProperties(object: any, properties: string[], strict: boolean /** * Check if an array of key exists in an object - * @function hasKeys({ hello: 'world' }, ['hello', 'world',]) + * @example hasKeys({ hello: 'world' }, ['hello', 'world',]) * @returns true */ export function hasKeys(object: any, keys: string[], strict: boolean = true): boolean {