Notes on NPM

After reading NPM’s documentation, I decided to jot down some notes to clarify things for myself.

Module vs. Package

Module is anything that can be loaded with require() in a Node.js program:

  • A folder with a package.json file containing a main field.
  • A folder with an index.js file in it.
  • A JavaScript file.

A package can be a multitude of things – URL, git URL, tarball, etc. – which resolve to a folder containing a program described by a package.json file. Note that it doesn’t mean it can be used in arequire(): one counter example is a package that provide a CLI and not a library

What does NPM mean?

It could mean different things

  1. The website
  2. The package registry
  3. The NPM CLI

NPM versioning

NPM packages are versioned using the following convention:



M- Major: updated when there are breaking changes to the package

m- Minor: when there are new feature, or changes that are non-breaking

p- Patches: used for patches or bug fix

Specifying versioning constraints:

  • Tilde (~) or 1.0.x, allows for patch upgrades, but maintains the Major and Minor version
  • Caret (^) or 1.x, allows for patch and Minor upgrades. Major version is fixed

CSS box model once and for all

From time to time, I forget the workings and attributes of the CSS box model. So, this time, I decided to write a blog post summarizing it and highlighting its logic. I hope this will make it easier to retain it.

In order to understand the box model, this post will be broken down in several sections relating to the model attributes. First, we’ll go over the existing types of boxes; then, how they are sized, positioned and floated; finally, how to make them responsive to the screen size.

Types of boxes

With the display attribute we can set the type of box we are using, for example

This div has attribute display: block. The borders are in black, so you can see that it stretches as far as it can to the left and to the right.

This one is a display: inline element. Its contents are wrapped inside a box that can be inlined with other inline elements.

With a display: none style, the element will not be rendered at all. This is different from the visibility: hidden style, in which the elements exist, take space, but are not shown.

Box sizing

The sizing of the box is defined with the width and height attributes. By default, this measure is of the content part only, so additional padding, border or margin add up to the total size of the box. This means that if you want the whole box (content + padding + border + margin) to fit a precise space, you need to do some math.

An alternative to this is to set the sizing measure to box-sizing: border-box. In this mode, the width and height defined will be the sum of the content, padding, border and margin. For example:

This box has width: 300px and
box-sizing: content-box (the default)
As you can see, the content measures 300px, but the border occupies an additional 10px
This other div has width: 300,
but box-sizing: border-box
So 300px is the measure of the entire box!

Since this is a recent addition to the CSS standard, some browser may require specific css tags to switch to box-sizing:

-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;

To apply this to all elements, just set the CSS style for all elements:

* {
-webkit-box-sizing: border-box;
   -moz-box-sizing: border-box;
        box-sizing: border-box;

Box Positioning

There are 4 attributes for positioning:

  • position: static the element follow the flow of the page and is considered to be not positioned – as a visual reminder, it’s flagged in red. The other attributes, in green, are considered positioned.
  • position: relative the element is translated, with the attributes left, right, top and bottom, relative to where it would be positioned. The element is translated, but it still occupies the original space in the document. In this sense it can overlap other elements and leave blank gaps in the document, as we will see in an example below.
  • position: absolute positions absolutely in relation to the parent box, which must have a positioned attribute (the green ones). It can be positioned using the left, right, top, bottom attributes.
  • position: fixed the element is fixed to the viewport. The box can be positioned using the left, right, top, bottom attributes.

In order to illustrate the types of positioning, some examples:

  • A relatively positioned div
a positioned div (position: relative)
a translated position: relative div overlapping the one above and leaving a blank space where it was located
another positioned div (position: relative)

  • A absolutely positioned div
a positioned div (position: relative)

a div absolutely positioned (position: absolute)

A fixed div… check the bottom right of your screen 😉

I’m a position: fixed div

Floating boxes

An element can be “floated” in order to wrap text around it:

I’m float: left !

In order to demonstrate the text wrapping, I’ll write a text that is long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long, long.
As you can see, it wraps around the float!

The problem with the floats is that the following div is still locked on the float:

I’m floated!

This div respect the float and wraps nicely around it.

This next div is locked on the float…

If the next div must break free from the float and appear after the floated element, it suffices to clear: left | right | both the float:

I’m floated!

This div respect the float, but the next one will break free from the float and appear below.

I’m a clear: left div, free from the float!

This float thing can be used to build a responsive web site. Try to resize the screen to see what happen to these divs:

float: left – A
float: left – B
float: left – C

Since they are floated, when there’s no more horizontal space, they are stacked on top of each other. Pretty nice, hum? But there’s more to responsiveness…

Responsive layout

The layout of the page can be changed depending on the size of the viewport using @media queries. When the query is valid, it is triggered, applying the designated styles. For example a menu on the left

Could be stacked on the top of the section when the screen becomes too small:

This is achieved with the following CSS

@media screen and (min-width: 600px) {
   nav     { float: left;
             width: 25%;}
   section { margin-left 25%}

@media screen and (max-width: 600px) {
   nav li  {display: inline }

The first block is applied when the viewport width is at least 600px. It aligns the nav to the left and the section to the top. If the screen size is under 600px, the first block of styling is not applied and the second one is. In this case, the divs will follow the usual behavior of occupying all the horizontal space and being one after the other.

Final Words

I believe this short summary could be used as cheatsheet when in doubt about the box model. I hope you enjoyed it.

A final remark, there’s an upgrade to the box model that is under development: the flexbox. This will be the subject of another post.

Hot or Cold? The 5º Celsius rule to know what to wear

If you are like me, you already found yourself in the uncomfortable situation of not knowing which clothes to bring for a trip, or what to bring for the day, if you live in a region with high temperature variations. For this, I have devised an empirical method, which I have called “the 5º Celsius rule”. It has been tested for the past 5 years and proved to be quite effective.

A caveat here: since I’m the only male subject to this model, there’s no statistical validity, so you’ll probably need to adapt it according to the workings of your body. For example, I guesstimate that for females, it would be the “4º Celsius rule”.

Anyway, here’s the 5ºC rule:

“You are at 25ºC, wearing shorts and T-shirt. For each decrease of 5ºC, you add another piece of clothing”

This rule is for a condition without any wind, so in more details:

  • 25°C : You are wearing shorts and T-shirt
  • 20°C : You either put some pants or a sweater
  • 15°C : You put the one missing from above (pants or sweater)
  • 10°C :  You’ll need a coat
  • 5°C : Gloves and a tuque (knit cap)
  • 0°C : Long underwear
  • <0°C : Get away from this place! (LOL)

So there you have it. Now you know how to fill your suitcase for your next trip =)

There’s no escaping the encoding: a quick explanation on Unicode vs. Encodings

TL;DR: there is no “plain text”, for every string or text file, one must know how it is encoded. There are two distinct concepts that must be emphasized: 1) Unicode, which is a set of character mapped to Code Points (usually represented by U+0000) and 2) Encoding, which is a map from the Code Points to the bit representation inside the computer (usually the bits are represented as hexadecimal, in the format 0x0000). If a text is decoded with the wrong “encoding”, characters may be misspelled or the ones that are missing are marked with question ??? marks.

Note: This is a big overview on encoding, focusing on its applicability.

Sooner or later, it always hit you: file encoding. It’s everywhere, in d3js, JavaScript, CSVs, Windows <=> Linux compatibility, Django, source files. There’s no escaping the encoding (pun intended).

I’ve always dreaded encoding issues, mainly because I’ve never really put an effort to understand it. If you are like me, most of times, we just figure out the code the fix the issue and move along.

But that rock is always on our path, making us trip at every pass, perhaps a change in perspective, it’s what it asks (nice accidental rhyme…). So what I’m proposing is to include this in the development process. Knowing the encoding is a pre-req every time we are working with strings/text, as Joel mention “It does not make sense to have a string without knowing what encoding it uses”

By turning this into a habit, we won’t be bitten back by a library that changes the encoding in the middle of our pipeline, or when our software scales to other languages. But first, we must understand a bit about this messy terms: Unicode, character set, UTF-8, Latin, etc.. Since images are a good way to represent ideas, here’s my take:


There are two different concepts that are usually blended together 1) Unicode which is a character set and 2) Encoding which is the bit representation of the character inside the computer.

There are two different concepts that are usually blended together: Unicode and Encoding. The Unicode Standard is a character set, an attempt to list all available characters in all the different languages. Its aim is to take into account every different letter, sign and symbol that exists… everything that people thought was necessary to represent their languages in the computers. Therefore there is no “Unicode encoding”, it’s just a set of characters.

In order to reference the symbols from Unicode, each one is mapped to a Code Point, which is usually represented in the U+0000 format. So for every symbol there is one Code Point, as can be seen on the examples of A..z, é, ã, à.

The other concept is the Encoding, which is the mapping between the Unicode character (Code Point) and it’s bit representation inside the computer. As you can see in the three different encoding examples (UTF, ISO-8859-1 Latin and ASCII), characters may have different bit representation.

Therefore, when a string or a text file is represented in the computer, it uses a specific encoding. Each symbol/Code Point is mapped to its bit value. Usually the encodings support a subset of the Unicode symbols, so if a text is decoded with the wrong “encoding”, characters may be misspelled or if they are missing, they may be marked by question ??? marks.

That’s why it’s so important to know the encoding in question: having the text or a string is just half of the story.

Some tools for poking at encoding

A tool in Linux that can be useful to poke at the file encoding and check its MIME is

$ file -i <file>

To convert to another encoding there is

$ encode [CHARSET] <file>

Dynamic vs. Static Typing

TL;DR: I’m sharing my view on Static vs. Dynamic typing after watching the Programming Languages Course @ Coursera. In the table below the key highlights:

Static typing Dynamic Typing
The object’s types are checked by the type checking system before the program is run The program is run without any type validation, it’s the developer’s burden to code the checking for when the program is executing (runtime)
At every part of the program the type of the objects used are known, so one’s assured that the right type of objects are being passed in the right places The type of the objects are known only at runtime. So if a wrong object type is being used, it will only show up during execution as a runtime exception.
The structure of the program is somewhat rigid, since a type must be defined for everything that is used Dynamic typing languages are more flexible, since you do not need to respect the type system
Changes in the program’s types structure are flagged by the type checking system and must all be corrected before running the program. Propagating changes in the type structure is responsibility of the developer, but subparts can be run before all the changes are implemented.

A few times I’ve tried understanding Dynamic vs. Static, but I never quite grasped it. I believe I didn’t get it because the mental model I was using wasn’t in line with what the writer had on it’s own, so we weren’t communicating on the same abstraction level.

It was during the Programming Language Course @ Coursera (a course that I strongly recommend if you don’t have a formal CS degree like me), that the professor, Dan, explained it in a way that finally made sense to me. In case there are other people wandering around, struggling to understand it, here’s my take on the subject:

  • Static Typing: it means that the types are/must be defined before the program executes (in a “static” environment). This done automatically by the type checking system, in which the object’s types are known at every line of the code. Therefore, before the program is even executed, there are no worries that there is a different than expected object being passed around. For example, if there is an object Foo being passed to a function, where an Array was expected, the type checking would fail before the program even start running. On the other hand in …

  • Dynamic Typing: there are no checks before the program is run. Any object type can be passed anywhere, provided that the syntax of the language is respected. For example, the if-then-elses parts must be in the correct order, but the language doesn’t care if there is a non-bool in the “if” part, or if the return types from the then/else branches are different. This means that in the code, objects of different types can be passed around without any restriction or error. The burden of type checking is passed to the developer.

    In case there are objects being passed with different types than expected, like in the previous example, it will be only at runtime that an exception will be thrown and the developer will be aware of the error. Since there’s no type checking system to watch over one’s shoulder, usually there are helper functions, like “is-of-type-X?” or similar, that will do the checking while the program is running (hence “dynamic” typing).

Spreadsheets and Excel – the “open source” modelling tool

In my life I had alternated periods of time in which I used Excel. I always wondered why such a simple tool has became so successful among people and companies. I was struck with the idea that a spreadsheet is an “open source” modelling tool.

The building block of the spreadsheets is very simple: just some cells in which you type formulas. The nice thing about this – macros apart – is that whatever is being calculated, you can take a peek inside it. In this way, you can walk your way through the document and understand every detail of what’s being modeled.

Other modelling softwares are usually more powerful, but they require the user to study and have deeper knowledge of the tool. The user is required to understand the inner workings of each functionality and each command. It’s not just “open document, start exploring”.

Moreover, the cells enforce the Functional paradigm, so that a formula contains reference to other cells only. There is no concept of state, no “for” loops, no local variables that you have to store in your brain to understand what’s happening.

Another point is that there is a limited set of functions and operations that one can use. This narrows the complexity the model can have. It either must comply with what’s available – and eventualy trade off a better quality model for simplicity – or be modeled elsewhere, in more powerful tools such as Matlab. In this sense, a spreadsheet is a threshold for model simplicity.

So let’s praise the spreadsheets for their simplicity and success!

Clojure Pedestal: a real-time webapp library, not a Web Framework

One of the difficulties when choosing among frameworks or libraries is to understand what does the framework or library can, can’t or requires lots of effort to do. I’m currently settling for a technology to develop a small scale website. Since I’m fond of Clojure, I’ve heard some fuss over Pedestal. I decided to study it and give it a try.

For starter, some people call it a “Web Framework”, but after reading about it, I go along with one of its authors, Tim Ewald, who says it’s more of a library. (You can hear him speaking about it on Pedestal Podcast at 5:05). This clarification is really enlightening, for you should not expect Pedestal to be a fully featured CMS system with database integration, etc. etc., such as Django or RoR.

So what is Pedestal?

Pedestal is a Clojure tool to build internet applications requiring real-time collaboration and targeting multiple platforms. It provides a clean architecture for creating large, interactive, single-page applications in the browser.

In other words, the library empowers one to create interactive web-apps for multiple users. This is achieved through a cleverly designed message queuing system that transforms the model and renders a new view to the users:


Overview of Pedestal inner-workings: users send message to the back end to transform the model. The messages are queued and applied to the model. Rendering function are then emitted to update the View.

This diagram illustrates the overall workings of the library. The users send their transformation messages to the back-end service. These messages are then queued and applied to the Info Model. Then rendering instructions are emitted so that the View is updated.

The library has additional functions to implement business logic when transforming the Model Info . For additional information see Derived Data and Continue Functions .

Bottom line is that Pedestal is not a Web Framework, but a powerful Clojure/Clojurescript library to tackle real-time web application with users interactions.