DEV Community: Will C.

Improve Your Javascript Codebase With Low Friction Typing Annotations

Will C. — Wed, 01 Apr 2020 02:24:02 +0000

For this trick, you will need VS Code as your IDE, and a mix of JSDoc/Typescript declaration file knowledge.

Background

I was recently working on a very large React codebase made by developers who made their own framework inside the app to manage displaying of widgets and visualizations in a dashboard.

The Problem

It was hard to follow the flow of data as it went against React's declarative style, and instead had a preference for configurations to define how the UI looked and worked.

This codebase was written for a fast moving start up, so of course, documentation was not a priority.

I wanted to make things easier for new people on boarding to reduce the amount of questions asked and file digging I had to do.

The Solution

I already knew from previous experience that VS Code had support for JSDoc. I discovered during my research that the types in JSDoc could also use Typescript declaration files!

This was awesome news, I could define types for all these different utility functions in my own declaration files, so that I would at least get some intellisense to help me when navigating the code base.

I then had the idea of expanding on this idea some more, and wanted to try using typescript declaration files defined by open source libraries. This way I could leverage all the documentation defined by library authors and @types contributors around the world.

After some failed google searching, I found the answer in the typescript docs of all places. In this reference, you can see the type being imported from a separate file of the project being used in the JSDoc. This got me thinking... could I import from a node_module ? Turns out, you can!

  /*
   * @param {string} chartType 
   * @returns {import ("highcharts/highcharts").Options} Returns a highchart options object used for defining your highchart component.
   */
   const getChartOptions = (chartType) => {
     // Some logic here...
     return { ...chartObject }
   }

With this simple JSDoc, the return object of the getChartOptions will get intellisense which will show all the available properties and a brief description of what it does when you hit ctrl+space. This is super useful when navigating something like a charting library which has types with several dozen properties and tons of nesting.

Summary

With a few extra comments in your javascript codebase loaded into VS Code, you can leverage a ton of documentation in an easily accessible way for developers.

No extra dependencies or vs code extensions were needed

Developers new to types can get a small taste of how much they help without having to fight a compiler.

Not having to open a browser to lookup API docs and staying in your IDE should avoid distracting yourself with the 20 different tabs you have open in Chrome.

I hope this short post will boost your team productivity. Let me know what you think in the comments and let me know if there is anything I could add to this way of making a codebase more accessible!

Lessons From Making My Own EventEmitter

Will C. — Mon, 09 Dec 2019 21:01:21 +0000

I recently completed a pramp practice problem that I found very enjoyable. It involved creating your own event emitter class in Javascript with the methods on, off, emit, and once.

on subscribes a call back to an event name.

off removes a callback from an event name.

emit calls all the callbacks associated with an event name and any arguments passed to emit.

once is similar to on, with the added logic of unsubscribing itself after being called once.

Creating the class and Subscribing

Let's start off by making the class and implementing the on method.

class EventEmitter {
  constructor(){
    this.events = {}
  }

  on(name, cb) {
    if (!this.events[name]) {
      this.events[name] = []
    }

    this.events[name].push(cb)
  }
}

Upon instantiation of an EventEmmitter class, an internal state housing all the event names is created. The on method takes a name string and cb function. The method will then add the cb to an array keyed to the event name. If no previous callbacks were added to this event name, a new key is created.

An example of this method in action:

const emitter = new EventEmitter()

emitter.on('click', () => console.log('I got clicked'))

Emitting and Unsubscribing

Now let's extend the EventEmitter class with some more functionality.

The actual emitting of an event can be done in a for loop, iterating through the cb's stored to an event name. In this example, I am using the ES6 spread (...) to store all the arguments passed to the emit and passed them to the callbacks within the loop.


// within EventEmitter class

  emit(name, ...args) {
    if (!this.events[name]) {
      // Ignore event names we don't have callbacks for.
      return;
    }

    for (let cb of this.events[name]) {
      cb(...args);
    }
  }

// usage
  emitter.emit("click")

Next let's unsubscribe a callback from an event name. Using this simple implementation, the only way to unsubscribe an event is by keeping a reference to the callback you made. We will need it for comparing the callbacks within the callback array. Later on in the blog post I'll talk about another method of unsubscribing.

// within EventEmitter class

  off(name, cb) {
    if (!this.events[name]) {
      return;
    }

    this.events[name] = this.events[name]
      .filter(callback => callback !== 
    cb);
  }

// usage
  const logClicks = () => console.log('I got clicked')
  emitter.on('click', logClicks)
  emitter.emit('click') // I got clicked!
  emitter.off('click, logClicks)
  emitter.emit('click') // Nothing happens.

Interesting Part

The final method, once, is where things get interesting. The imperative approach could be keeping a some additional internal state for once callbacks, and performing a check every time we run emit to see if the callback exists in the once state.

There is a much more elegant way of removing the once callback by leveraging javascript's first class treatment of functions.

Instead of storing more state, I can wrap the passed in callback with another function, and add some additional logic to it to remove itself after it gets called. This is what it would look like:

  once(name, cb) {

    this.on(name, function onceCB(...args) {
      cb(...args)
      this.off(name, onceCB)
    })
  }

Trying to run this code alone will not work though. this inside of onceCB is undefined! What do we do???

Context in Javascript

Context in javascript is a confusing topic that trips people up all the time. This is where some lesser known javascript APIs and arrow functions come in. Objects in Javascript have 3 methods that can be used for defining a this context. They include bind, call, and apply.

bind may be familiar with those who have some React experience. You would typically see a bind for methods that get passed as event handler functions. These methods need a bind to the component class they belong to because without it, the function would automatically bind to its nearest context where it gets called. In our case above, the function is being called in the global scope which is undefined.

call and apply are similar with a small difference. Both are used for invoking a function. Both take a context as its first parameter. call takes arguments individually, while apply takes an array of arguments. Either can be used interchangeably depending on your coding style or the coding styles defined by your project.

  someFunc(a, b)

  someFunc.call(this, a, b)

  someFunc.apply(this, [a,b])

Arrow functions, introduced in ES2015 (ES6) do a bit of magic behind the scenes, and automatically bind functions to the context where they are defined. This simplifies functions for developers as you usually want your functions to use the context where they were defined, reducing the overhead of remembering to bind.

Now that we know a bit more about how context works in javascript, let's look at some ways we can fix the once method above:

Using call or apply:

  // No need to modify the `once` method.

  emit(name, ...args) {
    if (!this.events[name]) {
      // Ignore event names we don't have callbacks for.
      return;
    }

    for (let cb of this.events[name]) {
-      cb(...args);
+      cb.apply(this, args); // or cb.call(this, ...args)
    }
  }

Using arrow functions:


  // No need to modify the `emit` method

  once (name, cb) {
-   this.on(name, function onceCB(...args) {
-     cb(...args)
-     this.off(name, onceCB)
-   })
+   const wrappedCB = (...args) => {
+     this.off(name, wrappedCB);
+     cb(...args);
+   };
+   this.on(name, wrappedCB);
  }

I tried to use bind in a similar fashion as the arrow function method but I was still getting the TypeError: Cannot read property 'off' of undefined error. I was able to get the once method to work without having to use apply or call in emit by storing a reference to this and using it in side of the wrappedCB

  once (name, cb) {
+   const self = this;
    this.on(name, function singleCB(...args) {
-     this.off(name, singleCB);
+     self.off(name, singleCB);
      cb(...args);
    });

Bonus round, a nicer Unsubscribe API

Having to store your callback for the sole purpose of unsubscribing is not the nicest API. You may prefer to just write the callback inline with the on call. The pattern I am about to show you is used in popular libraries like the Firebase Web client and jsdom to handle unsubscribing or cleaning up an instance.

Inside of the on method. instead of returning nothing, it can return a function which can call the off method for us.

// At the end of `on`

// using self
   const self = this;
   function cleanup() {
     self.off(name, cb);
   }
   return cleanup;

// or using arrow
   return () => {
     this.off(name, cb);
   };

// usage

const jelly = emitter.on('jelly', function(...args) console.log('jelly time', ...args))
emitter.emit('jelly', '1', '2', '3') // jelly 1 2 3
jelly() // unsubscribe the subscription
emitter.emit('jelly', '1', '2', '3') // nothing happens

Summary

Creating your own event emitter was a fun exercise. I got to practice the subscriber pattern in javascript which is typically abstracted away from me.

I got to see the motivation behind arrow functions and how they greatly simplify writing javascript applications.

Lastly, I got to use the apply and call methods for the first time! I typically focus on writing application logic so this change of scenery gave some great insight into what more advanced javascript looks like and helped me gain a better grasp of how this works.

If you made it this far I hope you have learned something new today and try this out on your own.

Until next time...

Here is the final working class

class EventEmitter {
  constructor() {
    this.events = {};
  }

  on(name, cb) {
    if (!this.events[name]) {
      this.events[name] = [];
    }

    this.events[name].push(cb);

    // using self
    // const self = this;
    // function cleanup() {
    //   self.off(name, cb);
    // }
    // return cleanup;

    // using arrow
    return () => {
      this.off(name, cb);
    };
  }

  once(name, cb) {
    // Using arrow:
    const wrappedCB = (...args) => {
      this.off(name, wrappedCB);
      cb(...args);
    };
    this.on(name, wrappedCB);

    // Using self object:
    // const self = this;
    // this.on(name, function wrappedCB(...args) {
    //   self.off(name, wrappedCB);
    //   cb(...args);
    // });

    // Original
    // this.on(name, function singleCB(...args) {
    //   this.off(name, singleCB);
    //   cb(...args);
    // });
  }

  emit(name, ...args) {
    if (!this.events[name]) {
      return;
    }

    for (let cb of this.events[name]) {
      cb(...args);
      // If not using arrow or self inside of `once`
      // cb.apply(this, args);
      // cb.call(this, ...args);
    }
  }

  off(name, cb) {
    if (!this.events[name]) {
      return;
    }

    this.events[name] = this.events[name].filter(callback => callback !== cb);
  }
}

3 Tips to Improve Your Git Workflow

Will C. — Mon, 25 Nov 2019 00:20:13 +0000

Photo by veeterzy on Unsplash

Bet on git

Any company that does development work should be using some form of version control. Git takes the cake as the industry standard. It is one of the most influential tools ever created and is one of the reasons open source has been so successful.

Looking at this visualization from 2004 to 2019, we can see Git's dominance over other version control systems.

Google Trends Query

I will share some tips to improve productivity and collaboration with team mates.

Use an alias library

Some git commands can be verbose. Things get worse if the files in your project have long names or files are deeply nested. The same goes for branch names.

My tool of choice to solve this is scm-breeze.

It's killer feature is mapping list outputs to numbers when you type in commands such as gs (git status) or gb (git branch). Now instead of git checkout some-long-branch-name-for-some-reason, you could instead run gb, look for the number that is mapped to your branch (lets say 3 for this example), and then run gco 3.

Example of a `git branch` command

Example of a `gb` command

There are a ton of other commands pre defined, just type git_aliases in your terminal after installing to see them.

Stage changes granularly

While working on a feature, you might be modifying various parts of your code to experiment. What do you do when you finish a piece of logic but only want to commit a small chunk of code? You might have made changes in other parts of the same file. Newbie me might have copied the changes I want to commit, reset the branch, and paste the changes back.

git add -p (or --patch) gives an interactive cli interface to add chunks of changes to staging instead of all the changes within the file. (This is gap in scm_breeze btw ;) ) At each chunk, you will see a prompt, where you can choose to either add, ignore, or edit the chunk.

On top of the granular control over what changes you want to add, I find this way of committing easier to digest. Instead of seeing a screen full or green and red, you have a few isolated lines of changes to look at.

Merge unrelated changes from a big feature branch early

There are times when you will be working on a feature that may take several days or weeks. While working on big changes like this, its common to notice small optimizations or refactors you need to make to other parts of the code base to support the feature you're working on.

Instead of hogging all these changes on your branch, waiting until your feature branch is ready for a PR, make a new branch off the dev/master branch and cherry pick the commits with these small optimizations. Start a new PR. Since its small the PR should be easier to review and merge with the main development branch. Then merge / rebase those changes back into your feature branch.

This type of workflow will make everyone on your team happier. Since we introduced these optimizations sooner, the rest of your team will get to benefit from your changes while you continue working on the big feature.

When you are ready to start a PR for that feature you've been working on, your reviewers will see a smaller diff. They will only see changes that are more focused on the feature you worked. This should make the PR easier to read and approve.

Closing remarks

Git-fu is a must have skill to be a productive developer. I hope this post has inspired you improve your git workflow. Try some of these out and let me know how things go! If you have any questions I'd be glad to go deeper in to the tips I discussed.

Happy coding!

DEV Community: Will C.

Improve Your Javascript Codebase With Low Friction Typing Annotations

Background

The Problem

The Solution

Summary

Lessons From Making My Own EventEmitter

Creating the class and Subscribing

Emitting and Unsubscribing

Interesting Part

Context in Javascript

Bonus round, a nicer Unsubscribe API

Summary

3 Tips to Improve Your Git Workflow

Bet on git

Use an alias library

Example of a git branch command

Example of a gb command

Stage changes granularly

Merge unrelated changes from a big feature branch early

Closing remarks

Example of a `git branch` command

Example of a `gb` command