Outline: Post about the FS module in NodeJS

Through research that I did both offline and online using several methods and through personal experience, the file system module in NodeJS is something that an individual despite the depth of experience they have usually look up to learn more about or refer to. The following outline will describe in detail about the topic, why I chose it, the structure etc. per the \newline guide on writing remarkable technical posts.

Topic: A journey to Asynchronous Programming with NodeJS FS.Promises API

Asynchronous programming is a topic that quite a lot of new developers struggle with to understand or do not fully understand enough to apply it properly in codebases. FS.Promises is a topic that newbies don't hear often about, they tend to use the callback versions of the methods in the fs module because they're higher up in the documentation. To make things worse, the number of tutorials regarding are much higher than those about fs.promises.

I believe a typical reader despite their level of experience that does not know about the topic or already has but has forgotten about it would look for (

please note that when I say "methods" I'm talking about the methods in fs

I use medium and dev.to quite a lot and I often come upon articles through reddit as well, some articles I read about fs.promises are:

While these articles describe what async programming is, what callback fs methods are etc. they do not go into any depth, no comparisons and contrasts are made etc. more or less looks like the docs but with a few more words. 

While this approach is perfectly suitable for someone who has sufficient experience in the field, wants to read about something really quick or wants to brush up on something that they found on the docs later on, it is not a good approach for a self learner or someone who wants to feel like they've learnt something or wants to learn more. They cover some of the topics(async/await, callbacks, util.promisfy) I plan on covering but nowhere nearly enough for someone to feel like they've learnt something new.

This is not the project structure, the following will more or less talk about what will be included in a more abstract manner, and to help me navigate myself during the process of writing. The article will include:

The typical look of a code example that will be used

Since this post will be more of a tour than a tutorial, I will use the two most used methods in FS, readFile() and writeFile(). So a typical code example would look like

const { promisify } = require('util');
const fs = require('fs');
const readFileAsync = promisify(fs.readFile);

try {
  const secretRecipe = readFileAsync('./notasecret.txt');
  console.log(secretRecipe)
} catch(err) {
  console.error(err) 
}

But to explain the event loop and call stack in the beginning, I will use a code example like this:

function showAnswer(answer) {
  console.log(answer)
}

function addAnotherFive(value) {
  const currentTotal = value + 5;
  showAnswer(currentTotal)
}

function addFive(value) {
  const currentTotal = value + 5;
  addAnotherFive(currentTotal)
}

addFive(10)

To explain the call stack, then provide external links. The purpose of this code example is to help the reader to visualize the explanations later on.

This post will be a tour in the words of the guideline, it will explain and teach a newbie and polish or add to the skillset of an experienced developer

The final post may look different and have a couple more things here and there but the overall structure will definitely not change in a drastic manner. I have chosen this topic after doing some research on reddit, then looking at search trends on Google Trends. I am considering the addition of an entire topic called bonus content, regarding File Streams, but without going off topic and some best practices when using fs methods like not using fs.access before fs.writeFile or fs.readFile etc.

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">Outline: Post about the FS module in NodeJS</h1>Through research that I did both offline and online using several methods and through personal experience, the file system module in NodeJS is something that an individual despite the depth of experience they have usually look up to learn more about or refer to. The following outline will describe in detail about the topic, why I chose it, the structure etc. per the \newline guide on writing remarkable technical posts.<h2><a name="topic-a-journey-to-asynchronous-programming-with-nodejs-fspromises-api">Topic: A journey to Asynchronous Programming with NodeJS FS.Promises API</a></h2>Asynchronous programming is a topic that quite a lot of new developers struggle with to understand or do not fully understand enough to apply it properly in codebases. FS.Promises is a topic that newbies don't hear often about, they tend to use the callback versions of the methods in the fs module because they're higher up in the documentation. To make things worse, the number of tutorials regarding are much higher than those about fs.promises.I believe a typical reader despite their level of experience that does not know about the topic or already has but has forgotten about it would look for (please note that when I say "methods" I'm talking about the methods in fs):<ul><li>How does async programming work?</li><li>What are promises? Why should I use promises or async/await over callbacks?</li><li>What is a synchronous method? When should I use them? Should they be avoided at all costs?</li><li>What is an async method? Why should I bother?</li><li>How was callback hell solved before Fs.promises?</li><li>What is Fs.Promises and why should I use it?</li><li>A summary on what the reader learnt. - What did I learn?</li><li>Where can I learn more from?</li></ul><h2><a name="research-about-other-similar-articles">Research about other similar articles</a></h2>I use medium and dev.to quite a lot and I often come upon articles through reddit as well, some articles I read about fs.promises are:<ul><li><a href="https://dev.to/mrm8488/from-callbacks-to-fspromises-to-handle-the-file-system-in-nodejs-56p2" rel="noopener noreferrer nofollow">From callbacks to FsPromise to handle the new file system in NodeJS</a></li><li><a href="https://medium.com/@hugolarrousse/read-write-a-file-node-js-2019-fs-promises-d234ca00f851" rel="noopener noreferrer nofollow">Read/Write a file in NodeJs 2019</a></li><li><a href="https://medium.com/@TheJesseLewis/promisifying-node-js-fs-with-es8-async-await-1ab98ff695d" rel="noopener noreferrer nofollow">Improving Node.JS I/O Operations with ES8 Async/Await and Util.promisify()</a></li></ul>While these articles describe what async programming is, what callback fs methods are etc. they do not go into any depth, no comparisons and contrasts are made etc. more or less looks like the docs but with a few more words. While this approach is perfectly suitable for someone who has sufficient experience in the field, wants to read about something really quick or wants to brush up on something that they found on the docs later on, it is not a good approach for a self learner or someone who wants to feel like they've learnt something or wants to learn more. They cover some of the topics(async/await, callbacks, util.promisfy) I plan on covering but nowhere nearly enough for someone to feel like they've learnt something new.<h2><a name="an-overview-of-the-article">An overview of the article</a></h2>This is not the project structure, the following will more or less talk about what will be included in a more abstract manner, and to help me navigate myself during the process of writing. The article will include:<ul><li>An overview of how the event loop and call stack works in NodeJS, and reference links to learn more about them.</li><li>A brief explanation about promises and async/await and how they compare with callbacks.</li><li>Code examples and explanation on how synchronous methods work and why they should be avoided whenever possible, but also ensure that the reader knows that there are times when synchronous methods can be used.</li><li>Code examples and explanation on how async callback methods work. Compare to previous topic about async callback. </li><li>A brief explanation and a code example on how util.promisify was used to achieve what Fs.Promises now do. Also briefly mention certain other libraries that did this ex promisfyAll from bluebird</li><li>Code examples and explanation on what Fs.Promises API is, why it should be used over the callback methods. </li><li>More in depth articles, reference guides and most importantly a tutorial or two to use what the reader learnt about. </li></ul><h2><a name="the-typical-look-of-a-code-example-that-will-be-used">The typical look of a code example that will be used</a></h2>Since this post will be more of a tour than a tutorial, I will use the two most used methods in FS, readFile() and writeFile(). So a typical code example would look like<textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-FoZJw" id="cm-FoZJw">const { promisify } = require('util');
const fs = require('fs');
const readFileAsync = promisify(fs.readFile);

try {
 const secretRecipe = readFileAsync('./notasecret.txt');
 console.log(secretRecipe)
} catch(err) {
 console.error(err) 
}</textarea>But to explain the event loop and call stack in the beginning, I will use a code example like this:<textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-jS3yY" id="cm-jS3yY">function showAnswer(answer) {
 console.log(answer)
}

function addAnotherFive(value) {
 const currentTotal = value + 5;
 showAnswer(currentTotal)
}

function addFive(value) {
 const currentTotal = value + 5;
 addAnotherFive(currentTotal)
}

addFive(10)</textarea>To explain the call stack, then provide external links. The purpose of this code example is to help the reader to visualize the explanations later on.<h2><a name="post-structure">Post structure</a></h2>This post will be a tour in the words of the guideline, it will explain and teach a newbie and polish or add to the skillset of an experienced developer<ol><li>Title</li><li>Introduction - Talks about the evolution of javascript, how nodejs is one of the most popular tools to use in the backend, why knowing something like this will help in the long run. What the filesystem does.</li><li>Summary - A warm up for the reader to know what they'll learn, will describe all the topics in few words.</li><li>Outcomes - By the end of the article they must know<ol><li>What an event loop/call stack is and how it fits with async programming</li><li>About synchronous methods and when to use them</li><li>About callback hell, the demerits of using callback methods in fs</li><li>That there are other libraries out there like bluebird that solved it, but now there's native support for fs modules with async/await, and their version numbers (Like when top level async/await became available)</li><li>To use fs.promise api next time to avoid callback hell</li></ol></li><li>Prerequisites - The reader must have had:<ol><li>Sufficient experience with writing Javascript aka be familiar with fundamentals like variables, functions etc.</li><li>Some level of experience with nodejs and the FS module (Optional)</li></ol></li><li>The content (May include more topics in the final post): <ol><li>The event loop and the call stack: How does the asynchronous flow work?</li><li>Promises and async/await: The solution to callback hell</li><li>Synchronous FS methods: What they are and when to use</li><li>Asynchronous FS methods: Why they are better and how</li><li>The history of promisifying FS </li><li>Fs.promises API: Native support! One less thing to worry about.</li></ol></li><li>Conclusion </li><li>Resources: (May include more in the final post)<ol><li><a href="https://eloquentjavascript.net/11_async.html" rel="noopener noreferrer nofollow">Eloquent Javascript: Asynchronous Programming</a></li><li><a href="https://nodejs.org/dist/latest-v10.x/docs/api/fs.html#fs_fs_promises_api" rel="noopener noreferrer nofollow">NodeJS Docs: Fs.promises</a></li><li><a href="https://www.youtube.com/watch?v=8aGhZQkoFbQ" rel="noopener noreferrer nofollow">JSConf Talk: What the heck is an event loop anyway?</a></li></ol></li></ol>The final post may look different and have a couple more things here and there but the overall structure will definitely not change in a drastic manner. I have chosen this topic after doing some research on reddit, then looking at search trends on Google Trends. I am considering the addition of an entire topic called bonus content, regarding File Streams, but without going off topic and some best practices when using fs methods like not using fs.access before fs.writeFile or fs.readFile etc.

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Outline: Post about the FS module in NodeJS

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript