Forem: Fernando Larrañaga

Data Structures with JavaScript: Queues

Fernando Larrañaga — Mon, 06 Jan 2020 18:17:07 +0000

Cover image by Florencia Viadana on Unsplash

¿Español? Puedes encontrar la versión traducida de este artículo aquí: Estructuras de datos con JavaScript — Parte 2: Colas (Queues)

This article is part of a series about data structures in JavaScript. The previous one can be found here:

Data Structures with JavaScript: Stacks

Fernando Larrañaga ・ Sep 30 '19

#javascript #beginners #programming #computerscience

Continuing this (not so) magical adventure with data structures in JavaScript, it is now time to talk about queues!

What is a queue?

A queue is a data structure very similar to a stack, meaning that it also operates in a linear and unidirectional way (elements are added from beginning to end). The main difference is in the way that elements are extracted from it. While a stack uses the LIFO (Last In First Out) principle, a queue uses the FIFO (First In First Out) principle instead. That means that the first element added to the queue will be the first one that will be extracted.

A common example to understand the behavior of a queue would be the line that we have to stand in when we go to the bank or a grocery store for checkout. In these lines, the person that is at the front of the line will be the first one to receive service.

graphic representation of a queue (sort of)

When to use a queue

Two of the most common uses for queues are present in tools and processes we probably use on a daily basis: Job queues, such as Resque, Sidekiq or Kue, and messaging services. In both cases, the data will be processed in a first-come-first-serve basis.

Complexity of a queue

The complexities of a queue are practically the same as the ones for stacks:

Time Complexity

Read: O(n)
Search: O(n)
Insert: O(1)
Delete: O(1)

Space complexity (in memory): O(n).

Methods/functionality of a queue

A well-implemented queue will need the provide methods that allow adding, remove and show elements, as well as return the current size of the queue. These methods are commonly named:

enqueue: Adds a new element at the end of the queue.
dequeue: Returns the first element, removing it from the queue.
peek: Returns the first element, without removing it from the queue.
size: Returns the number of elements of the queue.
print: Displays the content of the queue.

Optionally, some implementations also include a method called isEmpty. that will return a boolean (true/false) depending if the queue is empty or not. If the method is not available, we can infer such information by calling size.

How to implement a queue

The most direct way to implement a queue in JavaScript is by using an Array. Most of the methods we'll need are already implemented in its prototype, so we'll just have to create wrappers to return the values to the user.

The only additional method that we'll have to implement manually is peek, for which we'll return the first element of the array (of index 0).

class Queue {
  constructor() {
    // Initializes the queue as an empty string
    this.queue = [];
  }

  enqueue(element) {
    // Adds a new element by using push and returns the queue
    this.queue.push(element);
    return this.queue;
  }

  dequeue() {
    // Removes the first element by using shift
    return this.queue.shift();
  }

  peek() {
    // Shows the element in the first position
    return this.queue[0];
  }

  size() {
    // Returns the size of the array using length
    return this.queue.length;
  }

  isEmpty() {
    // Checks if there are no elements available by using length
    return this.queue.length === 0;
  }

  print() {
    // Displays the entire queue
    console.log(this.queue);
  }
}

const queue = new Queue();
console.log(queue.enqueue("The Rock")); // ["The Rock"]
console.log(queue.enqueue("Diamond Dallas Page")); // ["The Rock", "Diamond Dallas Page"]
console.log(queue.enqueue("Stone Cold Steve Austin")); // ["The Rock", "Diamond Dallas Page", "Stone Cold Steve Austin"]
console.log(queue.dequeue()); // "The Rock"
console.log(queue.peek()); // "Diamond Dallas Page"
console.log(queue.isEmpty()); // false
queue.print(); // ["Diamond Dallas Page", "Stone Cold Steve Austin"]

Source Code

You can find the source code of this example here:https://github.com/Xabadu/js-data-structures

Originally published on my blog at xabadu.dev

Build an SMS Panic Button with Twilio Functions

Fernando Larrañaga — Tue, 22 Oct 2019 19:22:01 +0000

Are you part of a nonprofit or social enterprise that wants to build things for social good? At Twilio.org, we offer discounts and credits to help you get started! Learn more.

In an emergency such as an accident, an insecure situation, or a natural disaster, a successful response time is often measured in seconds.

Communicating a call for help quickly is essential. If someone is unable to make a phone call or send a text message, a readily accessible panic button can enable them to make an urgent call for help discreetly and efficiently.

In this guide, we'll show you how to build an SMS Panic Button in a couple of steps using an IoT button and Twilio Functions.

Requirements

A free Twilio account
A Flic button (or any other button capable of sending an HTTP request)

How will this work?

IoT buttons, such as Flic, offer the possibility to configure and trigger different actions depending on what we do with them. In this case, we can link different outcomes to these 3 different actions:

A single press/click (the one we'll be using in this guide).
A double press/click.
A long press or hold.

On the other side, Twilio Functions allow you to send a request from any internet-connected device capable of sending outgoing HTTP requests, and from there interact with any Twilio API.

With these two pieces connected, we can build a flow that whenever we do a single click, sends an SMS to a preconfigured number.

What are we doing?

The logic of this entire flow works as follows:

We'll create a Twilio Function that has a predefined phone number and sends a message whenever an HTTP request comes in.
We'll configure our button to execute an outgoing HTTP request whenever someone executes a single button click.
We'll link the outgoing HTTP request to the path of the Twilio Function we created in Step 1.
We'll have an epic SMS panic button ready to go!

Creating your Twilio Function

Next, we’ll create a Twilio Function that receives the request after we click the Flic button and sends an SMS message to a list of numbers that we’ll define.

To do this, first go to the Manage Functions page in the Twilio Console, by accessing the Functions icon in the Runtime menu:

Now, create a new function, by clicking the red “Create new function” button:

Select “Blank” in the New Function wizard, and then click on “Create”:

Now, with your new function created, you’ll need to fill these two sections:

Function name: It's a friendly name, and it can be whatever you want. In this case, we are using "SMS Panic Button" as the name.
Path: It's the specific path for the URL associated with this function. It can also be whatever you want, but we recommend keeping it short, so it's easier to remember. In this case, we are using "/sms-panic-button". We are using this URL in the next section when we configure the action for the button.

Next, add this in the code section below:

const number = "your-number-here";

exports.handler = function(context, event, callback) {
  const twilioClient = context.getTwilioClient();

  twilioClient.messages.create(
    {
      from: "one-of-your-twilio-numbers",
      to: number,
      body: "This is a panic button test message"
    }, callback
  );
};

For this code, you need to configure two parts:

"your-number-here" (line 1): The destination number. Must be in e164 format (e.g: +1 1234567890)
"One-of-your-twilio-numbers" (line 8): Your Twilio number that sends the messages. You can get a phone number or look at your existing ones in the Active Numbers section in the Twilio console.

Finally, click "Save" to deploy the function.

Setting up your Flic button

After getting your Flic button and going through the initial setup (creating your account/signing in and connecting your button to the app), tap your button in the main screen of the app:

In the action selection screen, tap on the “Click” option to configure what happens when we do a single click with the button:

After selecting the single-click option and going to the configure action screen, scroll all the way down and select the “Tools” option:

And in the tools list, scroll down until you find the “Internet Request” option and select it:

Now, you’ll need to configure two things in the “Internet Request” details screen:

The Method: Select POST here.
URL: Here, you need to add the URL of the Twilio Function we created in the previous step.

After you fill those two options, scroll all the way down and tap the “Save Action” button:

And with that, your Panic button should be all good and ready to go. Next step is to try it out and see if everything is working correctly, but before we do that, one thing to keep in mind:

What if I want to text multiple numbers?

If you want to add more numbers as destination and notify more people after pressing your panic button, this guide walks you through sending multiple SMS messages to many different numbers.

Now, time for a demo!

Demo

Have any ideas on how to extend this or make it even better? Let us know! We can't wait to see what you build!

Got any questions or comments? You can find me on:

Email: flarranaga@twilio.com
Twitter: @xabadu
GitHub: Xabadu

Data Structures with JavaScript: Stacks

Fernando Larrañaga — Mon, 30 Sep 2019 16:25:40 +0000

Cover image by Clem Onojeghuo on Unsplash

¿Español? Puedes encontrar la versión traducida de este artículo aquí: Estructuras de datos con JavaScript — Parte 1: Pilas (Stacks)

Data Structures! - Now, now, before we start to panic, let's just take a deep breath and jump into this (not so) magical adventure to unveil the mysteries of the commonly feared data structures in JavaScript: What are they, what are they good for and most important of all, how to implement them.

In this article, we'll start with what's probably one of the most common ones: Stacks. So where do we start? At the beginning!

What is a stack?

A stack is a structure used to store data that functions in a linear and unidirectional way. That last part is really important because it sets the rules that we'll need to follow when working with stacks: Every element or piece of data added to a stack will be included in the same order and direction (from start to end).

Stacks manage their data under a principle called LIFO (Last In First Out). This means that the last element we add will always be the first one that will be extracted from it.

A commonly used analogy to describe stacks is to think of the way that plates are stored in a kitchen cabinet. Every time we go to grab a new plate, we'll always take the one that sits at the top, which coincidentally was the last one we put there. (Sometimes we'll try to be clever and take the one in the middle, but then the plates fall, break, and we'll get in trouble 🤕)

Let's look at a graphical representation of how a stack would work: (we'll go through what every part of this is later):

Looks like a stack

When to use a stack

There are a lot of practical examples that we can find nowadays where stacks are being used. There is also a good chance that we've been using them on a daily basis without even knowing. In fact, to get to this article, we did it with one of the most used stacks that there is: the navigation history of our browser. Every new page that we visit is stored on top of the previous one, and it creates a stack of values that allows us to go back, one by one (with the back button).

Additionally, stacks are useful when we need a data structure to store data that will be displayed in chronological order (such as a list of latest tweets or articles). For this example, the most recent piece of data added will be the first one shown, and so on, and so on.

So every time that we need to store data in order, and then remove that data from the last one to the first one added, a stack will be your best friend.

Complexity of a stack

Depending on the type of implementation of a stack (by using an array or an object), there are different levels of complexity, both for space (amount of memory that it will use) and time (how long it will take to perform operations on that stack, such as: adding, reading, searching and deleting elements).

(Note: Let's consider n = depending on the number of elements in the structure, 1 = direct access).

Space complexity

Array: O(n).
Object: O(n).

For both cases, the space complexity will be O(n), meaning that it will increase or decrease proportionally to the number of elements that are stored.

Time complexity

For an implementation using arrays:

Read: O(1)
Search: O(n)
Insert: O(n)
Delete: O(n)

An using objects:

Read: O(n)
Search: O(n)
Insert: O(1)
Delete: O(1)

Methods and/or functionality of a stack

Traditionally, a stack needs to have functionality that allows to add new elements, extract them, and review them. Even though we can choose whatever name we want for these methods, there is a convention of using the following names to define them:

push: Adds a new value at the end of the stack.
pop: Returns the last value, removing it from the stack.
peek: Returns the last value inserted, without removing it from the stack.
size: Returns the number of elements that the stack has.
print: Displays the contents of the stack.

How to implement a stack

Option 1: Using an array

Implementing a stack using arrays in JavaScript is relatively straightforward since most of the methods from the previous list are already included in the Array prototype implementation, so we only need to write a small wrapper that interacts with these methods and return the corresponding values.

The only method that we'll need to implement manually is peek, which will return the last value of the array, equal to the length of the array minus one (since arrays are zero index-based, but length shows the total amount of elements that the array contains, starting from 1).

The implementation would look something like this.

class Stack {
  constructor() {
    // we create and initialize the stack as an empty array.
    this.stack = [];
  }

  push(element) {
    // pushing an element uses the native push method.
    this.stack.push(element);
    return this.stack;
  }

  pop() {
    // pop will return the last element by using the native pop method.
    return this.stack.pop();
  }

  peek() {
    // peek checks the last element of the array by using the length
    // (total number of elements) minus 1 to find the right index.
    return this.stack[this.stack.length - 1];
  }

  size() {
    // size just returns the length of the array.
    return this.stack.length;
  }

  print() {
    // print will do a console log of the array
    console.log(this.stack);
  }
}

const stack = new Stack();
console.log(stack.size()); // 0
console.log(stack.push("Stone Cold Steve Austin")); // ["Stone Cold Steve Austin"]
console.log(stack.push("The Rock")); // ["Stone Cold Steve Austin", "The Rock"];
console.log(stack.size()); // 2
stack.print(); // ["Stone Cold Steve Austin", "The Rock"];
console.log(stack.peek()); // The Rock
console.log(stack.pop()); // The Rock
console.log(stack.peek()); // Stone Cold Steve Austin

Option 2: Using an object

Implementing a stack with an object requires a bit of additional work since the native methods of the arrays will not be available here, so we'll have to implement them manually.

One of the ways to achieve this is, when creating the stack, initialize a variable that will act as a cursor and keep the current position of the last element added, as well as the total number of elements inserted. Since the default behavior of a stack just requires us to add/remove the last element added, as long as we keep track of the current position, we should be able to achieve this.

constructor() {
  this.stack = {};
  this.count = 0;
}

To add elements, we'll use this.count as a reference of the current position and we'll use JavaScript's bracket notation to do a direct insertion in the object.

push(element) {
  this.stack[this.count] = element;
  this.count++;
  return this.stack;
}

For peek, print y size, the implementation is basically the same as with arrays. The main difference is that we'll use this.count instead of Array.length to identify the index of the element that we'll need to show or to return the total number of elements added.

peek() {
  return this.stack[this.count - 1];
}

size() {
  return this.count;
}

print() {
  console.log(this.stack);
}

Finally, for pop it'll be necessary to do some extra work. The difference with the last case is that after returning the element, we'll need to delete it from the object and move the cursor back to track the new last element.

pop() {
  this.count--;
  const element = this.stack[this.count];
  delete this.stack[this.count];
  return element;
}

The full implementation would be as follows:

class Stack {
  constructor() {
    this.stack = {};
    this.count = 0;
  }

  push(element) {
    this.stack[this.count] = element;
    this.count++;
    return this.stack;
  }

  pop() {
    this.count--;
    const element = this.stack[this.count];
    delete this.stack[this.count];
    return element;
  }

  peek() {
    return this.stack[this.count - 1];
  }

  size() {
    return this.count;
  }

  print() {
    console.log(this.stack);
  }
}

const stack = new Stack();
console.log(stack.size()); // 0
console.log(stack.push("Stone Cold Steve Austin")); // { "0": "Stone Cold Steve Austin" }
console.log(stack.size()); // 1
console.log(stack.peek()); // Stone Cold Steve Austin
console.log(stack.push("The Rock")); // { "0": "Stone Cold Steve Austin", "1": "The Rock" }
console.log(stack.size()); // 2
stack.print(); // { "0": "Stone Cold Steve Austin", "1": "The Rock" }
console.log(stack.peek()); // The Rock
console.log(stack.pop()); // The Rock
stack.print(); // { "0": "Stone Cold Steve Austin" }
console.log(stack.size()); // 1
console.log(stack.peek()); // Stone Cold Steve Austin

Source Code

You can find the source code of this example here:https://github.com/Xabadu/js-data-structures

Originally published on my blog at xabadu.dev

You, me and package.json

Fernando Larrañaga — Tue, 30 Jul 2019 15:36:17 +0000

¿Español? Puedes encontrar la versión traducida de este artículo aquí: Tú, yo, y package.json

If you have worked in a Node.js or client-side JavaScript project, there is a pretty good chance that you have seen a file called package.json, and that you've poked around its contents. Even though there is a lot of stuff in there that you probably are very familiar with, you may have run into some stuff that is not completely sure what it means or even how it got in there in the first place.

In this article, we'll go over the details of what each thing inside this file means, what kind of stuff you can put in there and how it can help you become even more productive while developing your projects.

But first things first:

What is the package.json file?

Historically, Node has been using a tool called npm to manage package and dependencies. This tool, which is usually installed along Node, has two main jobs:

Publishing your project to npm's public registry (so other users can download it as a dependency for their projects).
Manage the dependencies of your own project.

To be able to do this, the npm client creates and uses a file called package.json. This file contains information about the project such as:

Name.
Version.
Dependencies.
Repository.
Author(s).
License.

And more.

Additionally, as well as keeping a record, by using this file the integrity of the project can be guaranteed for everyone that gets a copy. This means that any user, at any point in time, will be able to access the same set of similar compatible dependencies. In a way, we can think of the package.json file as our project's manifesto. One thing to keep in mind here is that while the dependencies listed in a package.json file should be similar and compatible to the original ones, is not guaranteed that the project will be able to run without any issues if a considerable time has passed since the original declaration _(could be cases where changes were introduced in a different version of the package that is also considered compatible but could break some functionality). For this, is the use of lock files is recommended.

Let's look at an example by considering the following scenario:

Two devs are working on the same project, with independent copies in their own computers. Dev #1 decides that in order to complete the new feature, he'll need to use a new library inside the project.

Without any dependency management, he would need to do one of two things:

Manually download the library into the project's directory and keep a copy in there that has to be included wherever the project is being stored, potentially increasing the amount of data that needs to be transferred anytime a new Dev gets a copy.
Download a copy of the library without keeping a copy, but letting every person working on the project (present and future) know that they'll need to get a copy of it and making sure they're using the exact same version. (Good way to make new friends, but not so good in terms of time management).

With a dependency management tool, such as npm, neither of these steps are necessary anymore. Anyone that gets a copy of the project, now and forever (as long as the package hasn't been unpublished), will be able to install each and every one of the dependencies without the need to transfer the actual copies of them. As a result, the actual project that it's stored in a repository, and shared, is a lot lighter and redundant data is not being transferred.

It's worth mentioning that, even though a lot of the information contained inside a package.json file seems to be specific for publishing projects in the npm registry, we can still use npm to manage other kinds of projects that will never be published in there, such as Web and/or mobile apps, games, and others.

As a final note about dependency management, a while back, my very good friends at Facebook (note: They don't really know we're friends... yet :() launched a similar tool called yarn, which for all intents and purposes of this article is able to do the same two tasks we mentioned above, and its use of the package.json file is the same, unless explicitly stated.

How to create a package.json file

One rule, to ring them all (?)

Before creating a package.json file, there's one rule to know: The file must be in a valid JSON format and must abide by the JSON style spec.

With that in mind, there are 2 different ways to create the file: Manually or using the npm/yarn cli:

Creating the package.json manually

If for any reason the option of using the npm/yarn cli is not available and we really need to create a file manually, we'll need to add a new file (named package.json) to the root of the project containing the following fields:

name.
version.

Every other field (listed in the next section) is optional, though recommended.

Creating a package.json using the npm/yarn cli

This is the recommended way to do it. Creating a package.json file can be done by running any of these commands (depending on which package manager you're using) in the root directory of the project:

npm init

yarn init

Depending on whether npm or yarn is being used, certain information will have to be provided before the file is created:

Creating a package.json using npm

Creating a package.json using yarn

Once finished, a brand new package.json file will be created in the root directory of the project.

Quick tip: If you need to quickly create a package.json file with default values, you can run:

npm init -y

yarn init -y

The sections of the package.json file

After creating the package.json file, either manually or using the cli, we'll find inside a big object with different keys and values (like the initial image of this article). Also, as time passes and new dependencies/configurations are included, new keys and values will also be included here. The following is a list of the most common ones that we'll probably run into at some point in time:

Note: This list only includes properties officially declared and supported by npm. There are multiple external libraries that also support keys to read from the package.json file (ie. Jest and the property “jest”)

name

This is one of the two required fields that need to be included in the file (along with version). It's a string that represents the name of the current project and also works as a unique identifier in case the project is published in the registry.

Rules:

The name must be lowercase and cannot start with a period or an underscore.
The maximum length of the name is 214 characters and must be URL safe (more info about URL safe characters can be found here, section 2.3).

A few other things to keep in mind:

If the project will be published in the npm registry, the name must be unique and available (no other projects published before using the same name).
Even though it's considered a good practice to use related names if the package belongs to a certain technology (like using react-{something} for React libraries), it's also recommended to not use node or js in the name.

version

The other required field, along with the name. It's a string indicating the current version of the project. Node.js and JavaScript projects usually abide by the conventions defined in Semantic Versioning (or semver), which defines the following structure for versions:

MAJOR.MINOR.PATCH

More info about semver.

description

A string with a short explanation of what the project is about. If the package is ever published, this text will also be relevant for search results.

keywords

Same as description, but instead of text, it's an array of strings that includes relevant terms that can be used to search the package.

homepage

A string with a valid URL for the project's Website.

bugs

A string with a valid URL where users can report issues found in the project. Usually, the issues repository URL is used for this.

license

A string that specifies the type of license under which this project is being released. This can be personal, commercial, open, or private.

More info on available licenses.

author

It can either be a string or an object with information about the creator of the project.

If it's an object, must be in the following format:

name.
email.
URL.

And if it's a string:

"Name <email> (URL)"

contributors

Similar to author, it's an array of objects (or an array of strings) with the information of the contributors of the project.

files

An array of strings or patterns (such as *.js) of the files that will be included in the project if it's ever published in the registry. If this section is not defined, every file (that is not explicitly excluded in a file like .gitignore) will be included.

Some things to keep in mind about this:

By default, every file listed inside .gitignore will be excluded from publishing.
Instead of adding a files section, a .npmignore file can be included in the root of the project with a list of files to exclude from publishing (similar as what .gitignore does).
Some files will always be included, regardless of explicit exclusion. Amongst these files are: package.json, README, CHANGES / CHANGELOG / HISTORY, LICENSE / LICENCE, NOTICE and the file defined as an entry point of the app (more about this in the following section)
Some files will always be ignored, regardless of explicit inclusion. A list of these files can be found here.

main

A string that defines the entry point of the project. If the project is a package/library, this is the file that will be imported whenever someone requires it. For instance:

If your project is called super-awesome-library and a user installs it and then inside their app they do:

const superAwesomeLibrary = require("super-awesome-library");

the superAwesomeLibrary variable will have the contents of whatever your main file is exporting, so if your package.json file has a declaration such as:

{
  "main": "lib/foo.js"
}

then the superAwesomeLibrary variable will contain the content that is exported in lib/foo.js.

If this section is omitted, then the contents of the index.js file that lives in the root directory of the project will be used.

bin

A string (if it's only one) or an object (if it's multiple) defining scripts that will be installed and will be available as commands in the PATH. After the package is installed, a symbolic link will be created from /usr/local/bin to the respective file inside the project and will be available as a command-line program.

For instance, let's say we have a file called cli.js inside our project, and we wanna make it available for users to call it directly from their terminals. The way to achieve it would be to include a single string as bin inside package.json as follows:

{
  "name": "super-awesome-library",
  "bin": "cli.js"
}

Now the contents of cli.js can be used by running whatever we put as name of the project in the terminal:

super-awesome-library

While the user is running that friendly name, in reality, something like this is happening "behind the scenes":

node cli.js

And then whatever is on that file will be run.

If instead of that, we have multiple files that we want to turn into executable scripts, we can use the object format instead. This will add a symbolic link for every key-value pair, using the key as the command that will be available afterward:

{
  "bin": {
    "script-1": "super-h4x0r-script1.js",
    "script-2": "on-your-left.js"
  }
}

With that object, both “script-1” and “script-2” will be included in the PATH, each pointing to the respective .js file that was their pair inside the bin object.

This is what many known packages, such as nodemon or react-native, include so we can use them as terminal commands directly without having to run node whatever-the-path-to-the-file-is.

man

A string, or an array of strings, defining one (or many) file(s) that will be available/shown if the man command is run for this project.

directories

An object defining the structure of the project and where every folder is located for certain sections. The most common ones are bin, doc, example, lib, man, test.

{
  "bin": "./bin",
  "doc": "./doc",
  "lib": "./lib"
}

repository

An object defining where this project is stored and can be found for contribution. The object has the following format:

{
  "type": string,
  "url": string
}

Where type refers to the type of repository (such as svn or git) and URL is a valid URL where it can be found.

Example:

{
  "type": "git",
  "url": "https://github.com/my-user/super-awesome-project"
}

scripts

An object defining commands that can be used with the npm/yarn cli for the project. Some scripts are predefined and reserved and can be used without defining them, such as start, install, preinstall, pretest, test, and posttest amongst others. (a full list can be found here).

In the same way, we can define our own scripts and use custom names and instructions for them. This is very useful to create shortcuts and/or combined tasks without having to remember the full commands and/or params every time.

For instance, let's pretend that we have an app that needs to run a task to minify the JS files before creating a new version, and we do that with a script that lives in tasks/minify.js and passing a flag or param that uses internally. Usually, we would run node tasks/minify.js --someflag --maybeanother every time we want to achieve this (and we would need to remember the name of the flags as well). However, if we instead add it to the npm scripts, we could do something like:

"scripts": {
  "minify": "node tasks/minify.js --someflag --maybeanother"
}

And then run:

npm run minify

This achieves the exact same result. The cool thing about this is not only not having to remember the exact commands we need to run each time, but also that npm scripts can be combined and executed sequentially, so we can create complex tasks and even trigger some automatically if we use any of the pre hooks (like pretest or prepublish).

For instance, let's say that we want to run that same minify task, as well as run our code through a linter, right before we run the tests of our app. For that, we could add something like this (pretending our app code lives in the src folder):

"scripts": {
  "pretest": "node tasks/minify.js --someflag --maybeanother && eslint src"
}

Or we could include it directly as part of the test script (this example uses jest, but you can replace that with mocha/ava/tape/etc or the tool of your choice):

"scripts": {
  "test": "node tasks/minify.js --someflag --maybeanother && eslint src && jest"
}

As a final note about this, these scripts need to be run as npm run 'script' unless it's one of the predefined/reserved by npm (listed at the beginning of this section). However, if you are using yarn, you can omit the run part completely and just do yarn 'script', regardless of it it's a predefined script or not.

config

An object where values can be set to use as environment variables that can be later accessed from within your code.

To set a config value, we can do this inside the package.json file:

{
  "name": "my-app",
  "config": {
    "port": 8000
  }
}

And then, values can be referenced from within the code using process.env.npm_package_config_{value}, like this:

const express = require('express');
const app = express();
const port = process.env.npm_package_config_port;

app.get('/', (req, res) => res.send('Hello!'));

app.listen(port, () => console.log(`App listening on port ${port}!`));

These config values can be changed from outside the package.json file at any time by executing:

npm config set {name of the project}:{config key} {config value}

For our previous example, we could do something like this:

npm config set my-app:port 3000

dependencies

An object that stores the name and version of each dependency installed (and saved) during the project's history. Every time that someone gets a new copy of this project and runs npm install, all of these dependencies will be installed (with the newest compatible version). These dependencies, as well as the next two categories, are defined with the following format:

"name-of-the-dependency": "(^|~|version)|url"

Some examples:

"dependencies": {
  "backbone": "1.0.0",
  "lodash": "^4.6.1",
  "mocha": "~3.5.3",
  "super-mega-library": "https://example.com/super-mega-library-4.0.0.tar.gz"
}

These dependencies can have either the version installed and saved or a valid URL where the package with the current version can be obtained (this URL can also be a local path inside the same computer).

What are the ^ and ~ symbols at the beginning of the versions?

Every dependency installed can have a character defining the range of acceptable compatible versions. These 2 are the most commons, but a full list can be found here.

In other words, these characters add instructions on how this dependency should be treated the next time an npm install happens:

If the version has a caret (^): Allow installing a different version, as long as it's just a minor change (the second number of the version). If no different minor versions are found, the same version will be installed.
If the version has a tilde (~): Allows installing a different version, as long as it's just a patch change (the last number of the version). If no different patches are found, the same version will be installed.
If the version just has the number and no characters: The exact same version defined has to be installed.

For instance, with the dependencies specified above, if we run npm install and new versions are available:

backbone and super-mega-library would stay using the same versions (1.0.0 and 4.0.0 respectively).
lodash could either install the same version, or any versions between 4.6.1 and 4.9.9, but never anything equal to 5.x.x or above.
mocha could either install the same version, or any versions between 3.5.3 and 3.5.9, but never anything above that.

devDependencies

The same format as the dependencies listed above, but this section will include all the dependencies that the project uses but are not needed for a production environment (like testing tools, local dev servers, optimization tools, etc.). Any computer that gets a copy of this project and has production set as the NODE_ENV variable will not install the dependencies listed in this section.

peerDependencies

This uses the same format as well, but these dependencies while not necessarily installed, define the compatibility required for this app/package to work correctly. For instance, if we are developing a library that is only compatible with version 16 of React, we would need to do something like this:

"peerDependencies": {
  "react": "16.0.0"
}

Older versions of npm (1 and 2) used to install these peerDependencies automatically, but that's not the case anymore. As of version 3, if a compatible version is not found when this project is installed, a warning will be triggered.

engines

An object where we can define the minimum versions of node and npm that this project supports. It's defined in the following format:

"engines": {
  "node": ">= 6.0.0",
  "npm": ">= 3.0.0"
}

When the project is installed, a check will be run to assure the compatibility. If this is not met, the install process will stop.

As is the case with dependencies, we can use ranges (like **>=**, **^**, **~**, etc.) to define compatible versions.

More information

Even though these are the most common things we'll find and use inside a package.json file, there is still some additional ones that can be interesting or useful to check. For additional references, I'd recommend reviewing the official docs of npm on a regular basis, since it's constantly being updated anytime a new version is released.

Useful links:

Originally published on my blog at xabadu.dev

Getting started with Web Performance

Fernando Larrañaga — Wed, 22 May 2019 23:56:47 +0000

Performance is a term that we know we should be constantly thinking about (and working on), but for different reasons, we tend to forget about it. The truth is that it can be such an overwhelming topic that when face these issues, it's hard to know where to even begin.

And even though, nowadays we have a lot of tools that will help us test our apps to see how they're doing, at the same time understanding how they work can be a bit tricky (and sometimes really hard), so with the limited time we have, we often put it to the side because results seem to be less noticeable than other things like shipping a new feature or fixing a nasty bug.

In this article, I'll cover some initial notions on why should we care, how to get started and how to make it part of our daily workflows.

But first, it's a good idea to go over a few things to both understand the importance of performance and to set the right expectations about it:

Why should I care about performance?

While less noticeable at first glance, the performance of our app or Website can have an even bigger (and often negative) impact on our users, sometimes even driving them away and choosing to go to a different site. If your app belongs to a business, this could turn into an even worse result, driving customers away and losing a potential sale to a competitor that has a "faster" site than yours.

We can find plenty of stats shared by big companies about how delays of even 1 second or less while loading their content can impact their sales or drive traffic away, so it makes you wonder if that kind of impact can happen to well-known brands, what can it do to ours?

No silver bullet

Like most good things in life, having a performant app doesn't come easy, and it's important to understand that right off the bat. Working on performance related issues involve a lot of... well, work. Sadly, there's no miraculous package or library that we can use and will solve all of our problems (yet, who knows, maybe one day, you know, with like 🤖🤖🤖 and stuff), but that doesn't mean it's impossible to achieve, in fact, quite the opposite. The process of solving performance issues and improving our apps is relatively straightforward:

Collect some data.
Experiment.
Collect some new data and compare.
Draw conclusions (a.k.a keep what worked, undo what didn't).

While some of these parts might have different implications (and some of them might be a bit tricky), the process is always the same, which makes these two things even more important to keep in mind:

What works on some other app might not be the right thing for yours: This doesn't mean that good practices and general advice should be dismissed, it's often useful advice that will help us get there, just that it might not be right (or the biggest priority) for your use case.
Performance is, a lot of times, all about trade-offs.

Rewrites are less likely than improvements

As developers, a lot of times our first reaction when we get involved in a project that has issues is to think about rewriting that code. Truth is, most of the times, we won't be able to do so due to time constraints, budgets or other priorities. That's why it's a good idea to think about improving the current codebase we're working on instead of throwing it out and writing a new one. With this, we'll be able to compare results with actual data that has been live for a long time and get a better idea of the impact every change makes.

And, if we ever actually get to do a rewrite, there's a lot of things that we'll probably keep in mind to make it better.

So, with all of this in mind, how do we start?: With a plan.

Ready to make a plan

Going head first into working not knowing what we're supposed to achieve will probably cause more problems than it solves. Understanding what should be the focus of the work and making a plan on how to execute it will allow us to get actual wins that are relevant to the main purpose of our app.

Wait, purpose, what do you mean?

Identify the main goal of your application

When building an app, or a Website, probably one of the first questions we should ask ourselves is What is this app trying to achieve?. In most cases, the goal is pretty clear: sell something, show content, provide a service and so on. Now, while identifying the main goal can be straightforward, a lot of times it's hard to get a clear idea of how the app should focus to accomplish that goal.

That focus tends to be different between apps, especially if they fall under different categories, and it relates closely to where our performance efforts should be concentrating on.

For instance, let's say we build a Website to sell cookies. The main goal of the site would be pretty clear: selling those delightful 🍪🍪🍪. Now, when planning the features of the homepage of the site, we know we'll probably have these sections:

A header with a nice logo and a menu with cool animations.
A list with all the cookies available.
A sidebar with contact info, social media links, newsletter signup for promotions and some ads.
A cool footer with all the legal info.

If we go back to what our main goal is (selling cookies), and we think about the importance of each section and how it relates to the goal, we can probably assume that our users don't really care about some of the stuff on that list and that they're visiting the site to get some cookies (and that's what we want too). So with that in mind, we should probably put our efforts in showing them the list with the cookies first and as fast as possible instead of spending time and resources displaying the menu and the animations (as cool as they might be) or the sidebar with the social media links, so that's where our plan should focus on.

Make a plan for gradual improvements (5-10% at a time)

One very important thing to understand when talking about performance is that it's an ongoing effort and that it's very likely that we won't be able to fix every issue right away. A big part of this is measuring and experimentation, so there's a lot of back and forth between trying new things, analyzing trade-offs and making decisions based on that. As well, there's a pretty good chance that the changes we make will not have huge differences in terms of percentages, but that doesn't mean that are not wins, on the contrary, every improvement we make will have an impact on every user that visits our site and will make their experience better.

Think about it this way: If we have an app built with JavaScript, and it lives in a 500kb bundle file, a user that visits our site will be downloading 500kb of code that will have to be parsed, interpreted and compiled by their browsers. Now, let's say we find a way to make some improvements on that file and we end up decreasing the size of the bundle by 10%. Even though 10 doesn't seem like much, it's still 50kb less that we're sending (and that will need to be parsed, interpreted and compiled), so not only things will load faster, but our users will appreciate having to download less amount of data to use the app (especially those on mobile networks).

So, with that in mind, a good rule of thumb will be to plan for gradual improvements between 5-10% on each cycle of work. If we can get more, excellent, but everything between those numbers should be great and realistic since initially, the wins will be bigger and more noticeable, but as we progress, it'll be harder to find places for improvement. After every cycle of improvements, we can get some new samples and plan for the next one.

Get your data

The last step before getting to work is to get real data from the current performance of our app to identify the pain points and prioritize the work. We do that by measuring.

Measuring

Why you should measure

Whenever thinking about why should we measure, I like to think about these principles:

Sometimes things look fast, but they're not.
Sometimes things look ok but could be better.
Sometimes things look slow, but it's not their fault.

Browsers are faster than ever, so nowadays are able to do a lot of things faster than we can notice, but that doesn't necessarily mean that they are, indeed, fast. A lot of stuff happens underneath that we won't get a clear idea until we peek under the hood and see how everything is being loaded, how much time each part takes and if any of it it's causing issues.

By using tools to measure each part of our app, we'll get a clear picture of how everything's truly looking, and it'll be easier to identify the problems and plan the work.

How to measure

There is a lot of tooling these days that allow us to get a clear idea of how our app is performing, and even get some advice on how to improve any issues that are found. Out of those alternatives, the ones I like to use are:

Lighthouse (Web, CLI, CI)

Google Lighthouse is probably the best tool nowadays to run performance audits against our app. It takes care of checking different load scenarios, how we're handling resources and even give advice on how to improve any issues found, even when it comes to accessibility and SEO. The best thing about it, is that there are multiple ways to run it (through Google's Web Dev site, Chrome extension or even Chrome Dev Tools), and can even be incorporated to our daily workflow as a build check with their GitHub integration.

Lighthouse in Google's Web Dev site

Lighthouse in Chrome Dev Tools

PageSpeed Insights

A while back, if you measured a URL in PageSpeed Insights and Lighthouse, you would often get some different information, scores, and advice, so it is useful to run both and consolidate that information. Currently, it's a lot closer, but it doesn't hurt to actually keep checking on both to make sure we're tackling all the issues found.

PageSpeed Insights

Pingdom Website Speed Test

Running audits with an external tool like Pingdom is also useful to have extra data that we can compare. One of the cool things about this one, in particular, is that it allows us to test how our site is loading from different locations, so if we're reaching a global audience, we'll have a better idea of how they see our content.

Pingdom Website Speed Test

Chrome Dev Tools

And last, but certainly not least, it's the Performance Tab of Chrome Dev Tools, which will be one of our best friends while doing local development. With it, we can record everything that happens with our site while it loads, including how much code is being parsed, in what order, if we're making our CPU work too much and how long everything takes, which will give us a clear picture on potential bottlenecks that we should work on.

Performance Tab in Chrome Dev Tools

Prioritize issues and define the bigger impact

Remember a couple of sections ago where we discussed Identifying the main goal of your app? Now that we have real data and know where the pain points are, it's easier to get an idea of which of those are affecting that goal. With that in mind, defining priorities and putting together a list of things that will have the bigger impact it's important since those wins will not only benefit users but also whatever we're trying to achieve with our app.

Additional tips

Figure out how to fit performance into your planning (The good ol' 20%)

As it happens commonly with tests during software development, we need to change the way we think about performance and think of it as part of the process instead of an extra. The best way to do this and make it part of the culture of our teams is to try to find a way to include it as part of our planning. A good idea is, at the beginning of every sprint, to leave 10-20% of our time to work on performance issues. If we make this an ongoing effort and part of our weekly work, not only it'll become something everyone will care about, but eventually, there will be fewer problems to attack and efforts will not be as significant.

The good thing about performance improvements is that they're usually tied to wins for the business, so making a case to dedicate time to this is not as hard as other technical tasks like refactoring some code, improving tooling, and others.

Premature optimization

Premature optimization is one of the big gotchas when thinking about performance. It's easy to get caught up in thinking too far ahead and trying to come up with the best way to handle cases we may never reach, so it's a good idea to not worry about it too much at the beginning, but at the same time, keep an eye on things and try to identify possible issues that could arise at some point.

Test everything and everywhere

One of the big mistakes we usually make as developers is to test apps under the best conditions (locally, in our computer, with a fast internet connection). But we have to wonder, it's that the reality of our users? Probably not. That's why when testing it's a good idea to emulate different scenarios (slower CPUs or network connections) and see how our app behaves. It's important to remember that things always look great under the best conditions, but it's only under some constraints that we start seeing the cracks 😔.

Lucky for us, it's simple to simulate those conditions and test now, thanks to the Chrome Dev Tools:

Throttle CPU

How to throttle CPU in Chrome Dev Tools

Throttle Network

How to throttle the network in Chrome Dev Tools

Play around with those settings and reload your app, and that will allow you to see it under those simulated conditions.

Note: Those conditions are kept as long as Chrome Dev Tools is open. As soon as we close it, we'll go back to normal settings.

Get data about your users (devices, browsers) and see what they're using and what you should be thinking of

With tools like Google Analytics, it's easier than ever to get a clear idea of not only where your users are, but also what are they are using when visiting your site: browsers, devices, operating systems, and even screen resolutions. Having that data will be your superpower to figure out what your focus should be and to avoid wasted efforts.

For instance, if you collect data and realize that 100% of your users come to your site with the latest version of Chrome on Desktop, and no one is using other browsers or mobile devices, you could safely prioritize issues that are affecting them and not focus (so much) on your mobile version or supporting old versions of other browsers. On the contrary, not having that data could mean spending countless hours fixing bugs that will probably have zero impact on your users.

And now: Let's get to work!

And now that we have the data, the ideas and know what we need to focus on, it's time to get to work!. But, how do we do that? Well, that's for the next article ✌️.

Originally published on my blog at xabadu.dev