fixes #19 - adds further explanation about the introduced regex - [\.:]+

Author: ishtms

chapters/ch04.2-writing-logs.md

@@ -30,23 +30,23 @@ When logging is performed synchronously, each log entry is written immediately t
 
 By decoupling the logging process from the main application logic, we can achieve several advantages:
 
-- **Improved Performance:** Asynchronous logging allows the main application thread to continue executing without waiting for log writes to complete. This can be crucial for applications that require high responsiveness and throughput.
+-   **Improved Performance:** Asynchronous logging allows the main application thread to continue executing without waiting for log writes to complete. This can be crucial for applications that require high responsiveness and throughput.
 
-- **Reduced I/O Overhead:** Writing log messages to disk can be an I/O-intensive operation. By batching multiple log messages together and writing them in one go, you reduce the frequency of disk I/O operations, which can improve efficiency.
+-   **Reduced I/O Overhead:** Writing log messages to disk can be an I/O-intensive operation. By batching multiple log messages together and writing them in one go, you reduce the frequency of disk I/O operations, which can improve efficiency.
 
-- **Better Resource Utilization:** Asynchronous logging allows you to optimize resource utilization, such as managing concurrent log writes, handling errors without disrupting the main flow, and efficiently managing file handles.
+-   **Better Resource Utilization:** Asynchronous logging allows you to optimize resource utilization, such as managing concurrent log writes, handling errors without disrupting the main flow, and efficiently managing file handles.
 
-- **Enhanced Scalability:** Applications with multiple threads or processes benefit from asynchronous logging because it minimizes contention for resources like the log file. This is particularly valuable in scenarios where multiple components are concurrently generating log messages
+-   **Enhanced Scalability:** Applications with multiple threads or processes benefit from asynchronous logging because it minimizes contention for resources like the log file. This is particularly valuable in scenarios where multiple components are concurrently generating log messages
 
 ### 4. Getting Caller Information (Module and Line Number)
 
 Including caller information, such as the file name and line number from which a log message originated, can significantly enhance the effectiveness of our logging library. This feature provides contextual insight into where specific events occurred in the codebase, making it easier to identify the source of issues and troubleshoot them.
 
 When an application encounters an error or unexpected behavior, having access to the module and line number associated with the log message allows developers to:
 
-- Quickly locate the exact location in the code where the event occurred.
-- Understand the sequence of events leading up to the issue.
-- Make precise code adjustments to fix problems.
+-   Quickly locate the exact location in the code where the event occurred.
+-   Understand the sequence of events leading up to the issue.
+-   Make precise code adjustments to fix problems.
 
 Implementing this feature might involve using techniques from the programming language's stack trace or introspection mechanisms. Here's a high-level overview of how you could achieve this:
 
@@ -67,9 +67,9 @@ To do the testing, we'll create a new file `test.js` and a `config.json`. `test.
 ```js
 // test.js
 
-const { Logger, LogConfig } = require('./index')
+const { Logger, LogConfig } = require("./index");
 
-const logger = Logger.with_config(LogConfig.from_file('./config.json'));
+const logger = Logger.with_config(LogConfig.from_file("./config.json"));
 ```
 
 The `config.json` file has the following contents. You may try to tweak the values as well. Try putting in the values that aren't supported by us, and see whether the `assert` methods that we created actually crash the program or not?
@@ -117,7 +117,7 @@ class Logger {
     get size_threshold() {
         return this.#config.rolling_config.size_threshold;
     }
-    ...  
+    ...
 }
 ```
 
@@ -143,7 +143,7 @@ Error: time_option must be an instance of RollingConfig. Unsupported param 400
     at Function.assert (/Users/ishtmeet/Code/logtard/lib/utils/rolling-options.js:36:19)
 ```
 
-Why? Let's take a quick look at our `RollingTimeOptions` utility class 
+Why? Let's take a quick look at our `RollingTimeOptions` utility class
 
 ```js
 // file: lib/util/rolling-options.js
@@ -229,9 +229,9 @@ The "Don't Repeat Yourself" (DRY) principle is a basic concept in software devel
 
 DRY encourages developers to write clean, efficient, and modular code by:
 
-- Reducing the chances of errors: Duplicated code increases the chances of mistakes or bugs when changes are made in one place but not in others.
-- Simplifying maintenance: When a change is required, you only need to update the code in one place, making it easier to keep your codebase up-to-date and consistent.
-- Enhancing readability: Code that is free from unnecessary duplication is easier to understand and follow, making it more accessible to other developers.
+-   Reducing the chances of errors: Duplicated code increases the chances of mistakes or bugs when changes are made in one place but not in others.
+-   Simplifying maintenance: When a change is required, you only need to update the code in one place, making it easier to keep your codebase up-to-date and consistent.
+-   Enhancing readability: Code that is free from unnecessary duplication is easier to understand and follow, making it more accessible to other developers.
 
 Although following the DRY principle is generally beneficial, there can be situations where duplication might not necessarily be a bad thing. Not every instance of code repetition needs to be eliminated, and striving for absolute **DRY**ness in all cases might lead to overcomplicated solutions or premature abstraction.
 
@@ -357,7 +357,7 @@ class Logger {
 
         console.log('%s: %s', message, LogLevel.to_string(log_level))
     }
-    ...    
+    ...
 }
 ```
 
@@ -372,17 +372,17 @@ We only write logs based off the current logger's `log_level`
 
 ### Writing to a file
 
-We've been using `console.log()` to print the log messages to the standard output, or your terminal. However, there are many drawbacks to this approach. 
+We've been using `console.log()` to print the log messages to the standard output, or your terminal. However, there are many drawbacks to this approach.
 
 1. **Lack of Persistence:** Console logs are ephemeral and disappear once the application session ends (when you close the terminal or exit out of an ssh connection). This makes it challenging to review logs for past sessions.
 2. **Performance Impact:** Continuous console output can impact application performance, especially when generating a high volume of logs. It can slow down the application and interfere with its responsiveness. There are certain ways to get mitigate this, we'll talk about this in a later chapter.
 
 Create a private `log_file_handle` member
 
 ```js
-// file: lib/logger.js 
+// file: lib/logger.js
 
-const fs = require('node:fs/promises') 
+const fs = require('node:fs/promises')
 
 class Logger {
     ...
@@ -402,7 +402,7 @@ We'll expose a public method on the `Logger` called `init` and make that `async`
 
 ```js
 // file: lib/logger.js
-const fs = require('node:fs/promises') 
+const fs = require('node:fs/promises')
 
 class Logger {
     ...
@@ -426,29 +426,38 @@ There's a lot going on in this method. Let's break it down.
 
 3. `new Date().toISOString()` generates a string representation of the current date and time in the ISO 8601 format, such as "2023-08-18T15:30:00.000Z".
 
-4. `.replace(/\..+/, "")` is a regular expression operation. Let's break down the regex:
-   
-   - `\.` matches a literal dot character. Since the dot (`.`) is a special character in regular expression, known as a wildcard. It matches any single character except for a newline character (`\n`). This is useful when you want to match any character, which is often used in pattern matching. 
-     
-     However, in this case, we want to match a literal dot character in the string (the dot in the date-time format "00.000Z"). To achieve this, we need to escape the dot character by preceding it with a backslash (`\`). When you place a backslash before a special character, it indicates that you want to match the literal character itself, rather than its special meaning.
-   
-   - `.+` matches one or more of any character except newline. We match for all the characters following the dot.
-   
-   - `/g` is the global flag, indicating that the replacement should be applied to all occurrences of the pattern.
-   
-   - So, the regex `\..+` matches the dot and all characters after it in the string.
-   
-   - The replacement `""` removes the dot and all characters after it.
+4. `.replace(/[\.:]+/, "")` is a regular expression operation. Let's break down the regex:
+
+    - the square brackets [] are used to define a character class. A character class is a way to specify a set of characters from which a single character can match. For example:
+        - [abc] matches any single character that is either 'a', 'b', or 'c'.
+        - [0-9] matches any single digit from 0 to 9.
+        - [a-zA-Z] matches any single alphabetical character, regardless of case.
+        
+            You can also use special characters within character classes to match certain character types, like `\d` for digits, `\w` for word characters, `\s` for whitespace, etc.
+
+            In this case we are looking for all the dot (`.`) characters and colon (`:`) characters in the string.
+            
+    - `\.` matches a literal dot character. Since the dot (`.`) is a special character in regular expression, known as a wildcard. It matches any single character except for a newline character (`\n`). This is useful when you want to match any character, which is often used in pattern matching.
+
+        However, in this case, we want to match a literal dot character in the string (the dot in the date-time format "00.000Z"). To achieve this, we need to escape the dot character by preceding it with a backslash (`\`). When you place a backslash before a special character, it indicates that you want to match the literal character itself, rather than its special meaning.
+
+    - `+` matches one or more of any character except newline. We match for all the characters following the dot (.) and the (:) character.
+
+    - `/g` is the global flag, indicating that the replacement should be applied to all occurrences of the pattern.
+
+    - So, the regex `\..+` matches the dot and all characters after it in the string.
+
+    - The replacement `""` removes the dot and all characters after it.
 
 5. The result of the `replace` operation is a modified version of the ISO string, which now includes only the date and time portion, without the fractional seconds.
 
 6. `.log` is appended to the modified date and time string to form the final log file name.
 
 7. `await fs.open(file_name, "a+")` opens or creates the log file using the `fs.open` function with "a+" flag. We talked about the modes in a [previous chapter](https://github.com/ishtms/learn-nodejs-hard-way/blob/master/chapters/ch03-working-with-files.md#flag-argument)
-   
-   - If the file doesn't exist, it will be created.
-   - If the file exists, data can be appended to it.
-   - The `"a+"` mode allows both reading and appending. Appending means, we begin writing to the end of the file instead of from the 1st line. However, if the file is empty, it starts from the beginning. 
+
+    - If the file doesn't exist, it will be created.
+    - If the file exists, data can be appended to it.
+    - The `"a+"` mode allows both reading and appending. Appending means, we begin writing to the end of the file instead of from the 1st line. However, if the file is empty, it starts from the beginning.
 
 This code initializes the logger by creating or opening a log file with a name based on the current date. The regular expression is used to remove the fractional seconds from the ISO date string, and the resulting string is used as part of the log file name. This allows for creating a new log file every time the `init` method is called, typically representing logs for a specific time period.
 
@@ -480,11 +489,11 @@ And then call the `init` method from the `test.js`
 ```js
 // file: test.js
 
-const { Logger, LogConfig } = require('./index')
+const { Logger, LogConfig } = require("./index");
 
-const logger = Logger.with_config(LogConfig.from_file('./config.json'));
+const logger = Logger.with_config(LogConfig.from_file("./config.json"));
 await logger.init();
-console.log("Program exits.")
+console.log("Program exits.");
 ```
 
 However the output is strange
@@ -545,11 +554,11 @@ Let's fix this by using the `__dirname` global variable that we used earlier.
 ```js
 // file: test.js
 
-const path = require('node:path')
+const path = require("node:path");
 const { Logger, LogConfig } = require("./index");
 
 async function main() {
-    const logger = Logger.with_config(LogConfig.from_file(path.join(__dirname, 'config.json')));
+    const logger = Logger.with_config(LogConfig.from_file(path.join(__dirname, "config.json")));
     await logger.init();
     console.log("End of the file");
 }
@@ -586,7 +595,7 @@ Inside the `package.json` file, add a script `start` with the value of `node tes
     "scripts": {
         "start": "node test.js"
     },
-    ...    
+    ...
 }
 ```
 
@@ -611,7 +620,7 @@ If you do run `npm start`, it fails.
 
 ```bash
 ### Outputs
-[Error: ENOENT: no such file or directory, open 'logs/LogTar_2023-08-18T19:14:46.log'] 
+[Error: ENOENT: no such file or directory, open 'logs/LogTar_2023-08-18T19:14:46.log']
 ```
 
 It's failing because it could not find the `log` directory. If we mention something like this in our library's readme:
@@ -632,15 +641,17 @@ But, require is not just a function!
 
 For example:
 
-- `require.resolve('module-name')`: Returns the path of the module without actually loading it.
-- `require.cache`: Provides access to the cache of loaded modules.
-- `require.main`: Provides access to the `Module` object representing the entry script loaded when the Node.js process launched. This is exactly what we need.
+-   `require.resolve('module-name')`: Returns the path of the module without actually loading it.
+-   `require.cache`: Provides access to the cache of loaded modules.
+-   `require.main`: Provides access to the `Module` object representing the entry script loaded when the Node.js process launched. This is exactly what we need.
 
 The reason `require` might feel like both an object and a function is because JavaScript allows functions to have properties. You can test this yourself
 
 ```js
-function my_fun() { console.log('hi'); }
-my_fun.hey = 'there';
+function my_fun() {
+    console.log("hi");
+}
+my_fun.hey = "there";
 
 console.log(my_fun.hey); // there
 my_fun(); // 'hi'
@@ -653,8 +664,8 @@ Create a new file called `helpers.js` inside the `lib/utils` folder.
 ```js
 // file: lib/utils/helpers.js
 
-const fs_sync = require('node:fs');
-const path = require('path')
+const fs_sync = require("node:fs");
+const path = require("path");
 
 /**
  * @returns {fs_sync.PathLike} The path to the directory.
@@ -665,21 +676,21 @@ function check_and_create_dir(path_to_dir) {
         fs_sync.mkdirSync(log_dir, { recursive: true });
     }
 
-    return log_dir
+    return log_dir;
 }
 
 module.exports = {
-    check_and_create_dir
-}
+    check_and_create_dir,
+};
 ```
 
 Let's go through the `check_and_create_dir` function's code line by line.
 
 1. The `path.resolve()` function creates an absolute path by combining a sequence of paths or path segments.
-   
-   It processes the sequence from right to left, with each subsequent path added to the beginning until an absolute path is created. For example, if the path segments are `/foo`, `/bar`, and `baz`, calling `path.resolve('/foo', '/bar', 'baz')` would return `/bar/baz` because `'/bar' + '/' + 'baz'` creates an absolute path, but `'baz'` does not.
-   
-   If, after processing all the segments in the given path, an absolute path hasn't been created yet, then the current working directory is used instead.
+
+    It processes the sequence from right to left, with each subsequent path added to the beginning until an absolute path is created. For example, if the path segments are `/foo`, `/bar`, and `baz`, calling `path.resolve('/foo', '/bar', 'baz')` would return `/bar/baz` because `'/bar' + '/' + 'baz'` creates an absolute path, but `'baz'` does not.
+
+    If, after processing all the segments in the given path, an absolute path hasn't been created yet, then the current working directory is used instead.
 
 2. The `require.main.path` holds the absolute path to the directory of the entry point. The entry point is the `test.js` in our case. Or whatever file you specify while running `node file_name.js` command.
 
@@ -732,7 +743,7 @@ Instead of logging to the standard output, let's write it to the log file that i
 class Logger {
     ...
     async #log(message, log_level) {
-        // dont' write to the file if 
+        // dont' write to the file if
         //     1. The `log_level` argument is less than the `#config.level` value
         //     2. If the `fd` (file descriptor) is either 0 or -1, which means the file
         //        descriptor is closed or not opened yet.
@@ -756,14 +767,14 @@ const path = require("node:path");
 const { Logger, LogConfig } = require("./index");
 
 async function initialize_logger() {
-    let logger = Logger.with_config(LogConfig.from_file(path.join(__dirname, "config.json")))
+    let logger = Logger.with_config(LogConfig.from_file(path.join(__dirname, "config.json")));
     await logger.init();
 
     return logger;
 }
 async function main() {
     let logger = await initialize_logger();
-    logger.error('This is an error message');
+    logger.error("This is an error message");
 }
 
 main();