Update reading time functionality

Author: Invulner

README.md

@@ -3,7 +3,7 @@
 </div>
 
 <p align="center">
-  A lightweight React hook for analyzing text and providing various statistics such as word count, character count, search frequency, and more.
+  A lightweight React hook for analyzing text and providing various statistics such as estimated reading time, search frequency, word count, and more.
 </p>
 
 <div align="center">
@@ -31,7 +31,9 @@ yarn add use-text-analyzer
 
 - **Lightweight 🪶:** Less than 1KB in size, making it lightweight and efficient.
 - **TypeScript Support 🇹🇸:** Works seamlessly with both JavaScript and TypeScript projects.
-- **Efficient Algorithms ⚡:** Utilizes efficient algorithms for finding the most and least frequent words/characters.
+- **Advanced Reading Time Estimation 🕒:** Provides detailed reading time estimates in minutes and seconds, along with a human-readable format for immediate use in interfaces.
+- **Efficient Algorithms ⚡:** Utilizes efficient algorithms for finding the most and least frequent words/
+  characters.
 
 ## Usage 📝
 
@@ -60,14 +62,18 @@ function TextAnalyzerExample() {
   return (
     <div>
       <h2>Text Analysis Result</h2>
+      <p>
+        Estimated reading time: {readingTime.minutes}m {readingTime.seconds}s
+      </p>
+      <p>Total reading time in seconds: {readingTime.total}</p>
+      <p>Human-readable reading time: {readingTime.text}</p>
+      <p>
+        Search frequency of '{searchTerm}': {searchFrequency}
+      </p>
       <p>Word count: {wordCount}</p>
       <p>Character count: {charCount}</p>
       <p>Sentence count: {sentenceCount}</p>
       <p>Paragraph count: {paragraphCount}</p>
-      <p>
-        Search frequency of '{searchTerm}': {searchFrequency}
-      </p>
-      <p>Estimated reading time: {readingTime} seconds</p>
       <p>Most frequent word: {mostFrequentWord}</p>
       <p>Least frequent word: {leastFrequentWord}</p>
       <p>Most frequent character: {mostFrequentCharacter}</p>
@@ -87,22 +93,27 @@ A React hook that analyzes the given text and returns various statistics about i
 
 #### Parameters
 
-- `options` (required): An object containing options for text analysis.
+- `options` (`TextAnalyzerOptions`, required): An object containing options for text analysis.
   - `text` (string, required): The text to analyze.
   - `searchTerm` (string, optional): The term to search for in the text.
   - `ignoreCase` (boolean, optional, default: true): Whether to ignore case when searching for the term and calculating word and character frequencies.
   - `trimText` (boolean, optional, default: true): Whether to trim the text before analysis.
+  - `wordsPerMinute` (number, optional, default: 250): Custom reading speed in words per minute.
 
 #### Returns
 
-An object containing various statistics about the text.
+A `TextAnalysisResult` object containing various statistics about the text.
 
+- `readingTime` (object):
+  - `minutes` (number): The total estimated reading time expressed in whole minutes.
+  - `seconds` (number): Remaining seconds beyond the counted minutes.
+  - `total` (number): The total estimated reading time expressed in total seconds.
+  - `text` (string): A human-readable summary of the reading time.
+- `searchFrequency` (number): The frequency of the search term in the text.
 - `wordCount` (number): The number of words in the text.
 - `charCount` (number): The number of characters in the text.
 - `sentenceCount` (number): The number of sentences in the text.
 - `paragraphCount` (number): The number of paragraphs in the text.
-- `searchFrequency` (number): The frequency of the search term in the text.
-- `readingTime` (number): The estimated reading time of the text in seconds.
 - `mostFrequentWord` (string): The most frequent word in the text.
 - `leastFrequentWord` (string): The least frequent word in the text.
 - `mostFrequentCharacter` (string): The most frequent character in the text.

package.json

@@ -44,6 +44,8 @@
     "text-analysis",
     "word-frequency",
     "wordcount",
+    "reading",
+    "time",
     "reading-time"
   ],
   "author": "invulner <[email protected]>",

src/constants/index.ts

@@ -1,2 +1,6 @@
-// Assuming average reading speed of 200 words per minute
-export const WORDS_PER_MINUTE = 200;
+// The default reading speed is set to 250 words per minute.
+// This rate is an average based on extensive research into reading habits.
+// https://www.sciencedirect.com/science/article/abs/pii/S0749596X19300786
+// Users can adjust this setting to match their reading speed or the specific
+// requirements of different text types.
+export const WORDS_PER_MINUTE = 250;

src/interfaces/index.ts

@@ -20,6 +20,11 @@ export interface TextAnalyzerOptions {
    * @default true
    */
   trimText?: boolean;
+  /**
+   * The number of words a person can read per minute.
+   * @default 250
+   */
+  wordsPerMinute?: number;
 }
 
 /**
@@ -47,9 +52,26 @@ export interface TextAnalysisResult {
    */
   searchFrequency: number;
   /**
-   * The estimated reading time of the text in seconds.
+   * The estimated reading time of the text, detailed in minutes and seconds.
    */
-  readingTime: number;
+  readingTime: {
+    /**
+     * Estimated minutes to read the text.
+     */
+    minutes: number;
+    /**
+     * Remaining seconds beyond counted minutes.
+     */
+    seconds: number;
+    /**
+     * Total estimated reading time in seconds.
+     */
+    total: number;
+    /**
+     * Human-readable summary of the reading time.
+     */
+    text: string;
+  };
   /**
    * The most frequent word in the text.
    */

src/useTextAnalyzer.ts

@@ -2,6 +2,7 @@ import { useMemo } from 'react';
 
 import { TextAnalysisResult, TextAnalyzerOptions } from './interfaces';
 import { calculateStats } from './utils/calculateStats';
+import { WORDS_PER_MINUTE } from './constants';
 
 /**
  * Analyzes the given text and returns various statistics about it.
@@ -13,12 +14,18 @@ function useTextAnalyzer({
   searchTerm = '',
   ignoreCase = true,
   trimText = true,
+  wordsPerMinute = WORDS_PER_MINUTE,
 }: TextAnalyzerOptions): TextAnalysisResult {
   const processedText = trimText ? text.trim() : text;
 
   const analysisResult = useMemo(() => {
-    return calculateStats(processedText, searchTerm, ignoreCase);
-  }, [processedText, searchTerm, ignoreCase]);
+    return calculateStats({
+      text: processedText,
+      searchTerm,
+      ignoreCase,
+      wordsPerMinute,
+    });
+  }, [processedText, searchTerm, ignoreCase, wordsPerMinute]);
 
   return analysisResult;
 }

src/utils/calculateStats.ts

@@ -8,22 +8,25 @@ import { calculateCharFrequencies } from './calculateCharFrequencies';
 import { calculateWordFrequencies } from './calculateWordFrequencies';
 import { findMostAndLeastFrequent } from './findMostAndLeastFrequent';
 
-import { TextAnalysisResult } from '../interfaces';
+import { TextAnalysisResult, TextAnalyzerOptions } from '../interfaces';
 
 /**
- * Calculates text analysis statistics.
- * @param text - The text to analyze.
- * @param searchTerm - The term to search for.
- * @param ignoreCase - Whether to ignore case when searching for the term and calculating word and character frequencies.
- * @returns The text analysis statistics.
+ * Analyzes the given text and returns various statistics about it.
+ * @param {TextAnalyzerOptions} options - Options for text analysis.
+ * @returns {TextAnalysisResult} An object containing various statistics about the text.
  */
-export function calculateStats(text: string, searchTerm: string, ignoreCase: boolean): TextAnalysisResult {
+export function calculateStats({
+  text,
+  searchTerm,
+  ignoreCase,
+  wordsPerMinute,
+}: TextAnalyzerOptions): TextAnalysisResult {
   const wordCount = countWords(text);
   const charCount = countCharacters(text);
   const sentenceCount = countSentences(text);
   const paragraphCount = countParagraphs(text);
   const searchFrequency = countSearchFrequency(text, searchTerm, ignoreCase);
-  const readingTime = estimateReadingTime(wordCount);
+  const readingTime = estimateReadingTime(wordCount, wordsPerMinute);
   const wordsMap = calculateWordFrequencies(text, ignoreCase);
   const charsMap = calculateCharFrequencies(text, ignoreCase);
   const [mostFrequentWord, leastFrequentWord] = findMostAndLeastFrequent(wordsMap);

src/utils/common/formatReadingTimeText.ts

@@ -0,0 +1,12 @@
+/**
+ * Formats the reading time into a human-readable string.
+ * @param {number} minutes - The total number of minutes.
+ * @returns {string} The formatted reading time as a human-readable string.
+ */
+export function formatReadingTimeText(minutes: number): string {
+  if (minutes < 1) {
+    return 'less than a minute read';
+  }
+
+  return `${minutes} min read`;
+}

src/utils/estimateReadingTime.ts

@@ -1,10 +1,30 @@
-import { WORDS_PER_MINUTE } from '../constants';
+import { formatReadingTimeText } from './common/formatReadingTimeText';
 
 /**
  * Estimates the reading time of the text in seconds.
- * @param {number} wordCount - The number of words in the text.
+ * @param wordCount - The number of words in the text.
+ * @param wordsPerMinute - The number of words a person can read per minute (optional, default from constants).
  * @returns {number} The estimated reading time of the text in seconds.
  */
-export function estimateReadingTime(wordCount: number): number {
-  return Math.ceil(wordCount / (WORDS_PER_MINUTE / 60));
+export function estimateReadingTime(
+  wordCount: number,
+  wordsPerMinute: number,
+): {
+  minutes: number;
+  seconds: number;
+  total: number;
+  text: string;
+} {
+  const totalMinutes = wordCount / wordsPerMinute;
+  const roundedMinutes = Math.floor(totalMinutes);
+  const seconds = Math.round((totalMinutes - roundedMinutes) * 60);
+  const totalSeconds = Math.round(totalMinutes * 60);
+  const readableText = formatReadingTimeText(roundedMinutes);
+
+  return {
+    minutes: roundedMinutes,
+    seconds,
+    total: totalSeconds,
+    text: readableText,
+  };
 }