DEV Community: Hugo Di Francesco

Celebrating the publication of "Professional JavaScript" with the Dev.to family

Hugo Di Francesco — Sun, 20 Oct 2019 12:20:47 +0000

"Professional JavaScript" (which I've a co-authored), has recently been published with Packt, it's currently the #1 new release in the "Internet Web Browsers" category on Amazon: https://www.amazon.com/dp/1838820213

As a first-time author I was very grateful to work with the editorial team and the other authors. Publishing a book was a longer-term goal for me, which I've now achieved ahead of schedule and the experience has expanded my horizons as a writer.

Edit 2 I've sent through a list of people for the review referral scheme
If anyone is interested in a free ebook copy through the Packt review referral scheme, fill out the form:

Edit 1: I may reach the referral limit soon, if you're interested, I suggest still filling out the form anyhow and I'll see with my editor 😊

Thanks again to the amazing team at Packt and everyone who has worked on this (Vinicius Isola, Siyuan Gao, Philip Kirkbride).

To anyone who has ever read, liked, shared any of my posts anywhere on the internet, thanks! I wouldn't have got here without your support and readership.

Yarn Workspaces: monorepo management without Lerna for applications and coding examples

Hugo Di Francesco — Mon, 05 Aug 2019 00:00:00 +0000

How to use Yarn Workspaces to manage applications/coding examples.

Lerna isn’t required when you don’t need the git diffing and versioning facilites.

What’s more Yarn Workspaces are a great lightweight tool to get up and running faster for simple Node.js monorepo actions.

Example monorepo at: github.com/HugoDF/yarn-workspaces-simple-monorepo

Yarn Workspaces vs Lerna

Pros of using workspaces: Yarn Workspaces are part of the standard Yarn toolchain (not downloading an extra dependency). It’s very limited in scope, and de-dupes your installs (ie. makes them faster). This is perfect for managing code examples or a monorepo of applications.

Cons of workspaces: If you’re dealing with a monorepo of packages (npm modules, libraries), Lerna provides tooling around publishing/testing only changed files.

Note: Lerna and Yarn Workspaces are in fact designed to work together, just use "npmClient": "yarn" in your lerna.json. See the Yarn Workspaces Documentation for a short word about the comparison to Lerna.

Set up Yarn Workspaces

{
"private": true,
"workspaces": ["examples/*", "other-example"]
}

The directory structure looks like the following:

graph LR;r[root];r-->example;example-->example-1;example-->example-2;r-->other-example;

Note : each of the workspaces (packages) need to have a package.json with a unique name and a valid version. The root package.json doesn’t need to, it just needs to have "private": true and "workspaces": [].

Bootstrapping the monorepo

Equivalent with Lerna would include a lerna bootstrap, which run npm install in all the packages.

With workspaces since the dependencies are locked from root, you just need to do a yarn at the top-level.

For workspaces to work, your “workspace” folders need to have a package.json that contain a name and version.

Managing your monorepo with `yarn workspace` and `yarn workspaces` commands

Run commands in a single package

To run commands in a single package in your monorepo, use the following syntax:

yarn workspace <package-name> <yarn-command>

For example:

$ yarn workspace example-1 run test
yarn workspace v1.x.x
yarn run v1.x.x
$ node test.js
test from example 1
✨ Done in 0.23s.
✨ Done in 0.86s.

$ yarn workspace example-2 remove lodash.omit
yarn workspace v1.x.x
yarn remove v1.x.x
[1/2] 🗑 Removing module lodash.omit...
[2/2] 🔨 Regenerating lockfile and installing missing dependencies...
success Uninstalled packages.
✨ Done in 2.83s.
✨ Done in 3.58s.

“package-name” should be the value of found in the package.json under the name key.

Run commands in all packages

To run commands in every package in your monorepo, use the following syntax:

yarn workspaces <yarn-command>

For example:

$ yarn workspaces run test
yarn workspaces v1.x.x
yarn run v1.x.x
$ node test.js
test from example 1
✨ Done in 0.22s.
yarn run v1.x.x
$ node test.js
{ public: 'data' } 'Should not display "secret"'
✨ Done in 0.23s.
yarn run v1.x.x
$ echo "Other Example"
Other Example
✨ Done in 0.11s.
✨ Done in 2.15s.

$ yarn workspaces run add lodash.omit@latest
yarn workspaces v1.x.x
yarn add v1.x.x
[1/4] 🔍 Resolving packages...
[2/4] 🚚 Fetching packages...
[3/4] 🔗 Linking dependencies...
[4/4] 🔨 Building fresh packages...
success Saved 1 new dependency.
info Direct dependencies
info All dependencies
└─ lodash.omit@4.5.0
✨ Done in 3.31s.
yarn add v1.x.x
[1/4] 🔍 Resolving packages...
[2/4] 🚚 Fetching packages...
[3/4] 🔗 Linking dependencies...
[4/4] 🔨 Building fresh packages...
success Saved 1 new dependency.
info Direct dependencies
info All dependencies
└─ lodash.omit@4.5.0
✨ Done in 2.76s.
yarn add v1.x.x
[1/4] 🔍 Resolving packages...
[2/4] 🚚 Fetching packages...
[3/4] 🔗 Linking dependencies...
[4/4] 🔨 Building fresh packages...
success Saved 1 new dependency.
info Direct dependencies
info All dependencies
└─ lodash.omit@4.5.0
✨ Done in 2.63s.
✨ Done in 10.82s.

Example monorepo at: github.com/HugoDF/yarn-workspaces-simple-monorepo

unsplash-logo
Martin Adams

Jest Full and Partial Mock/Spy of CommonJS and ES6 Module Imports

Hugo Di Francesco — Mon, 29 Jul 2019 00:00:00 +0000

JavaScript import/require module testing do’s and don’ts with Jest

The example repository is available at github.com/HugoDF/mock-spy-module-import.

This post goes through how to achieve different types of module mocking scenarios with Jest.

From simple Import interception, to how to approach stubbing out an internal function call or Mocking only part of a module (by spying…).

These are methods that work in more specific cases than what the Jest official documentation shows.

This isn’t strictly a Jest testing guide, the same principles can be applied to any application/tests that need to mock CommonJS or ES Modules.

For Context: types of imports

Modern JavaScript has 2 types of imports:

CommonJS: Node.js’ built-in import system which uses calls to a global require('module-y') function, packages on npm expose a CommonJS compatible entry file.
ES Modules (ESM): modules as defined by the ECMAScript standard. It uses import x from 'module-y' syntax.

There are also (legacy) module loaders like RequireJS and AMD but CommonJS and ESM are the current and future most widespread module definition formats for JavaScript.

ES Modules have 2 types of exports: named exports and default exports.

A named export looks likes this: export function myFunc() {} or export const a = 1.

A default export looks like this: export default somethingAlreadyDefined.

A named export can be imported by itself using syntax that looks (and works) a bit like object destructuring: import { myFunc, a } from './some-module'.

It can also be imported as a namespace: import * as moduleY from './module-y' (can now use moduleY.myFunc() and moduleY.a).

A default export can only be imported with a default import: import whateverIsDefault from './moduleY'.

Theses 2 types of imports can also be mixed and matched, see import docs on MDN.

Intercepting imports

When unit-testing, you may want to stub/mock out module(s) that have their own battery of unit tests.

In Jest, this is done with jest.mock('./path/of/module/to/mock', () => ({ /* fake module */ })).

In this case the CommonJS and ES6 Module mocks look quite similar. There are a few general gotchas.

First off, what you’re mocking with (2nd parameter of jest.mock) is a factory for the module. ie. it’s a function that returns a mock module object.

Second, if you want to reference a variable from the parent scope of jest.mock (you want to define your mock module instance for example), you need to prefix the variable name with mock.For example:

const mockDb = {
get: jest.fn(),
set: jest.fn()
};
const db = mockDb
// This works
jest.mock('./db', () => mockDb);
// This doesn't work
jest.mock('./db', () => db);

Finally, you should call jest.mock before importing the module under test (which itself imports the module we just mocked).

In practice, Babel ESM -> CommonJS transpilation hoists the jest.mock call so it’s usually not an issue 🤷‍♀.

The CommonJS case

The full test and code under test is at examples/intercept-imports-cjs.

The relevant snippets are the following:

jest.mock('./db', () => ({
get: jest.fn(),
set: jest.fn()
}));
const mockDb = require('./db');
const {addTodo, getTodo} = require('./lib');
test('CommonJS > addTodo > inserts with new id', async () => {
await addTodo({name: 'new todo'});
expect(mockDb.set).toHaveBeenCalledWith('todos:1', {name: 'new todo', id: 1});
});
test('CommonJS > getTodo > returns output of db.get', async () => {
mockDb.get.mockResolvedValueOnce({
id: 1,
name: 'todo-1'
});
const expected = {
id: 1,
name: 'todo-1'
};
const actual = await getTodo(1);
expect(mockDb.get).toHaveBeenCalledWith('todos:1');
expect(actual).toEqual(expected);
});

ES Modules default export

The full test and code under test is at examples/intercept-imports-esm-default.

import mockDb from './db';
import lib from './lib';
jest.mock('./db', () => ({
get: jest.fn(),
set: jest.fn()
}));
const {addTodo, getTodo} = lib;
test('ESM Default Export > addTodo > inserts with new id', async () => {
await addTodo({name: 'new todo'});
expect(mockDb.set).toHaveBeenCalledWith('todos:1', {name: 'new todo', id: 1});
});
test('ESM Default Export > getTodo > returns output of db.get', async () => {
mockDb.get.mockResolvedValueOnce({
id: 1,
name: 'todo-1'
});
const expected = {
id: 1,
name: 'todo-1'
};
const actual = await getTodo(1);
expect(mockDb.get).toHaveBeenCalledWith('todos:1');
expect(actual).toEqual(expected);
});

ES Modules named export

The full test and code under test is at examples/intercept-imports-esm-named.

import * as mockDb from './db';
import {addTodo, getTodo} from './lib';
jest.mock('./db', () => ({
get: jest.fn(),
set: jest.fn()
}));
test('ESM named export > addTodo > inserts with new id', async () => {
await addTodo({name: 'new todo'});
expect(mockDb.set).toHaveBeenCalledWith('todos:1', {name: 'new todo', id: 1});
});
test('ESM named export > getTodo > returns output of db.get', async () => {
mockDb.get.mockResolvedValueOnce({
id: 1,
name: 'todo-1'
});
const expected = {
id: 1,
name: 'todo-1'
};
const actual = await getTodo(1);
expect(mockDb.get).toHaveBeenCalledWith('todos:1');
expect(actual).toEqual(expected);
});

Spying/Stubbing calls to internal module functions

Warning: you should not be spying/stubbing module internals, that’s your test reaching into the implementation, which means test and code under test are tightly coupled

Concept: “calling through” (as opposed to mocking).

An internal/private/helper function that isn’t exported should be tested through its public interface, ie. not by calling it, since it’s not exported, but by calling the function that calls it.

Testing its functionality is the responsibility of the tests of the function(s) that consume said helper.

This is for the cases where:

you don’t have the time to extract the function but the complexity is too high to test through (from the function under test into the internal function)
- solution: you should probably make time
the internal function belongs in said module but its complexity make it unwieldy to test through.
- solution: you should probably extract it
the function is not strictly internal, it’s exported and unit tested, thereforce calling through would duplicate the tests.
- solution: you should definitely extract it

In the following cases we’ll be looking to stub/mock/spy the internal makeKey function. This is purely for academic purposes since, we’ve shown in the section above how to test through the getTodo call.

In that situation we were testing expect(mockDb.get).toHaveBeenCalledWith('todos:1'); (see examples/intercept-imports-cjs/lib.jest-test.js). The generation of the todos:1 key is the functionality of makeKey, that’s an example of testing by calling through.

CommonJS

A module where internal functions can’t be mocked

Code listing lifted from examples/spy-internal-calls-cjs/lib.fail.js.

const db = require('./db');
const keyPrefix = 'todos';
const makeKey = key => `${keyPrefix}:${key}`;
function getTodo(id) {
return db.get(makeKey(id));
}
module.exports = {
makeKey,
getTodo
};

As you can see when you run the examples/spy-internal-calls-cjs/lib.fail.jest-test.js tests, there’s no way to intercept calls to makeKey.

A module where internal function can be mocked

Code listing lifted from examples/spy-internal-calls-cjs/lib.js.

const db = require('./db');
const keyPrefix = 'todos';
const makeKey = key => `${keyPrefix}:${key}`;
const lib = {
// Could also define makeKey inline like so:
 // makeKey(key) { return `${keyPrefix}:${key}` },
 makeKey,
getTodo(id) {
return db.get(lib.makeKey(id));
}
};
module.exports = lib;

Mocking/Spying the internal function

Code listing lifted from examples/spy-internal-calls-cjs/lib.jest-test.js

// ignore setup code
test("CommonJS > Mocking destructured makeKey doesn't work", async () => {
const mockMakeKey = jest.fn(() => 'mock-key');
makeKey = mockMakeKey;
await getTodo(1);
expect(makeKey).not.toHaveBeenCalled();
expect(mockDb.get).not.toHaveBeenCalledWith('mock-key');
});
test('CommonJS > Mocking lib.makeKey works', async () => {
const mockMakeKey = jest.fn(() => 'mock-key');
lib.makeKey = mockMakeKey;
await getTodo(1);
expect(mockMakeKey).toHaveBeenCalledWith(1);
expect(mockDb.get).toHaveBeenCalledWith('mock-key');
});
test('CommonJS > Spying lib.makeKey works', async () => {
const makeKeySpy = jest
.spyOn(lib, 'makeKey')
.mockImplementationOnce(() => 'mock-key');
await getTodo(1);
expect(makeKeySpy).toHaveBeenCalled();
expect(mockDb.get).toHaveBeenCalledWith('mock-key');
});

From the above we can see that with the setup from the previous section (see examples/spy-internal-calls-cjs/lib.js), we’re able to both replace the implementation of lib.makeKey with a mock and spy on it.

We’re still unable to replace our reference to it. That’s because when we destructure lib to extract makeKey we create a copy of the reference ie. makeKey = newValue changes the implementation of the makeKey variable we have in our test file but doesn’t replace the behaviour of lib.makeKey (which is what getTodo is calling).

To illustrate:

const lib = require('./lib');
let {makeKey} = lib;
makeKey = 'something';
// `lib.makeKey` and `makeKey` are now different...

ES Modules

Difficulty of Named exports

In the case of ES6 Modules, semantically, it’s quite difficult to set the code up in a way that would work with named exports, the following code doesn’t quite work:

import db from './db';
const keyPrefix = 'todos';
export const makeKey = key => `${keyPrefix}:${key}`;
export function getTodo(id) {
return db.get(makeKey(id));
}

Code listing lifted from examples/spy-internal-calls-esm/lib.named-export.js, tests showing there’s no simple way to mock/spy on makeKey are at examples/spy-internal-calls-esm/lib.named-export.jest-test.js

Unmockeable modules with default exports

Code listing lifted from examples/spy-internal-calls-esm/lib.default-export.js.

import db from './db';
const keyPrefix = 'todos';
const makeKey = key => `${keyPrefix}:${key}`;
function getTodo(id) {
return db.get(makeKey(id));
}
const lib = {
makeKey,
getTodo
};
export default lib;

Tests showing there’s no simple way to mock/spy on makeKey are at examples/spy-internal-calls-esm/lib.default-export.jest-test.js.

The reason this doesn’t work is the same as the CommonJS example, makeKey is directly referenced and that reference can’t be modified from outside of the module.

Anything attempting import it would make a copy and therefore wouldn’t modify the internal reference.

Mock/Spy setup with ESM

Code listing lifted from examples/spy-internal-calls-esm/lib.js

import db from './db';
const keyPrefix = 'todos';
const makeKey = key => `${keyPrefix}:${key}`;
const lib = {
// Could also define makeKey inline like so:
 // makeKey(key) { return `${keyPrefix}:${key}` },
 makeKey,
getTodo(id) {
return db.get(lib.makeKey(id));
}
};
export default lib;

Passing tests for the above are at examples/spy-internal-calls-esm/lib.jest-test.js

Note , it would be possible to do something similar with named exports:

import db from './db';
const keyPrefix = 'todos';
const makeKey = key => `${keyPrefix}:${key}`;
export const lib = {
// Could also define makeKey inline like so:
 // makeKey(key) { return `${keyPrefix}:${key}` },
 makeKey,
getTodo(id) {
return db.get(lib.makeKey(id));
}
};

The key point is around exporting a lib object and referencing that same object when calling makeKey.

Mocking internals is the same with ESM/CommonJS

Being able to mock a part of a module is all about references.

If a function is calling another function using a reference that’s not accessible from outside of the module (more specifically from our the test), then it can’t be mocked.

Spy on imports or mock part of a module by “referencing the module”

Warning: this will cause you to change the way you write your code just to accomodate a specific type of testing.

This will break if anyone decides to get a copy of the module’s function instead of calling module.fn() directly.

CommonJS: Spy import/mock part of a module with Jest

Code listing lifted from examples/spy-module-cjs/lib.js.

Note how the db module is imported without destructuring and how any calls to it are done using db.method() calls.

const db = require('./db');
const keyPrefix = 'todos';
const makeKey = key => `${keyPrefix}:${key}`;
let autoId = 1;
async function addTodo(todo) {
const id = autoId++;
const insertable = {
...todo,
id
};
await db.set(makeKey(id), insertable);
}
function getTodo(id) {
return db.get(makeKey(id));
}
module.exports = {
addTodo,
getTodo
};

We are now able to spy on db.method using the following approach:

const db = require('./db');
const {addTodo, getTodo} = require('./lib');
beforeEach(() => jest.clearAllMocks());
test('CommonJS > addTodo > inserts with new id', async () => {
const dbSetSpy = jest.spyOn(db, 'set').mockImplementation(() => {});
await addTodo({name: 'new todo'});
expect(dbSetSpy).toHaveBeenCalledWith('todos:1', {name: 'new todo', id: 1});
});
test('CommonJS > getTodo > returns output of db.get', async () => {
const dbGetSpy = jest.spyOn(db, 'get').mockResolvedValueOnce({
id: 1,
name: 'todo-1'
});
const expected = {
id: 1,
name: 'todo-1'
};
const actual = await getTodo(1);
expect(dbGetSpy).toHaveBeenCalledWith('todos:1');
expect(actual).toEqual(expected);
});

Notice how we’re not calling jest.mock(). Instead we’re mocking/spying only a specific function of the module when we need to by modifying the db module implementation.

ES6 Modules: Spy import/mock part of a module with Jest

Default exports

Assuming our db.js module exports in the following manner (see examples/spy-module-esm-default/db.js):

const data = {};
async function get(k) {
return data[k];
}
async function set(k, v) {
data[k] = v;
}
const db = {
get,
set
};
export default db;

We can then import it as follows (code listing lifted from examples/spy-module-esm-default/lib.js):

import db from './db';
const keyPrefix = 'todos';
const makeKey = key => `${keyPrefix}:${key}`;
let autoId = 1;
function addTodo(todo) {
const id = autoId++;
const insertable = {
...todo,
id
};
return db.set(makeKey(id), insertable);
}
function getTodo(id) {
return db.get(makeKey(id));
}
const lib = {
addTodo,
getTodo
};
export default lib;

Spying on the import/mocking part of the module becomes possible in the following fashion (full code at examples/spy-module-esm-default/lib.jest-test.js):

import db from './db';
import lib from './lib';
const {addTodo, getTodo} = lib;
beforeEach(() => jest.clearAllMocks());
test('ESM Default Export > addTodo > inserts with new id', async () => {
const dbSetSpy = jest.spyOn(db, 'set').mockImplementationOnce(() => {});
await addTodo({name: 'new todo'});
expect(dbSetSpy).toHaveBeenCalledWith('todos:1', {name: 'new todo', id: 1});
});
test('ESM Default Export > getTodo > returns output of db.get', async () => {
const dbGetSpy = jest.spyOn(db, 'get').mockResolvedValueOnce({
id: 1,
name: 'todo-1'
});
const expected = {
id: 1,
name: 'todo-1'
};
const actual = await getTodo(1);
expect(dbGetSpy).toHaveBeenCalledWith('todos:1');
expect(actual).toEqual(expected);
});

Notice how we don’t mock the db module with a jest.mock() call. Again we spy on the method that we’re interested in stubbing/spying for a particular test.

We leverage mockImplementationOnce() to avoid calling the real function (which you might not always want to do).

Named exports + “import * as alias from ‘module-name’”

Note: I’ve not read the full spec, the fact that this works might be a quirk of the Babel ES2015 module transpilation

Assuming we’ve defined db.js as follows (using named exports, see the file at examples/spy-module-esm-named/db.js):

const data = {};
export async function get(k) {
return data[k];
}
export async function set(k, v) {
data[k] = v;
}

We can import all the named exports under an alias with import * as db from './db' (code listing lifted from examples/spy-module-esm-named/lib.js):

import * as db from './db';
const keyPrefix = 'todos';
const makeKey = key => `${keyPrefix}:${key}`;
let autoId = 1;
export function addTodo(todo) {
const id = autoId++;
const insertable = {
...todo,
id
};
return db.set(makeKey(id), insertable);
}
export function getTodo(id) {
return db.get(makeKey(id));
}

The calls to db.set and db.get can be spied/mocked using the following approach (full code test file at examples/spy-module-esm-named/lib.jest-test.js):

import * as db from './db';
import {addTodo, getTodo} from './lib';
beforeEach(() => jest.clearAllMocks());
test('ESM named export > addTodo > inserts with new id', async () => {
const dbSetSpy = jest.spyOn(db, 'set').mockImplementationOnce(() => {});
await addTodo({name: 'new todo'});
expect(dbSetSpy).toHaveBeenCalledWith('todos:1', {name: 'new todo', id: 1});
});
test('ESM named export > getTodo > returns output of db.get', async () => {
const dbGetSpy = jest.spyOn(db, 'get').mockResolvedValueOnce({
id: 1,
name: 'todo-1'
});
const expected = {
id: 1,
name: 'todo-1'
};
const actual = await getTodo(1);
expect(dbGetSpy).toHaveBeenCalledWith('todos:1');
expect(actual).toEqual(expected);
});

Add Search to a Hugo site with Lunr.js and Node.js

Hugo Di Francesco — Mon, 01 Jul 2019 00:00:00 +0000

Hugo “The world’s fastest framework for building websites” is a great option for JAMStack (JavaScript, APIs, prebuild Markup) sites.

Lunr.js is “A bit like Solr, but much smaller and not as bright”, it’s a pure JavaScript implementation of a Solr-like search engine.

One of the only things it doesn’t provide out of the box is Search. It does give you a few options to integrate at “Search for your Hugo Website”.

None were plug and play so I wrote my own simple solution using Lunr.js, a small Node.js script and a few lines of client-side HTML/JavaScript code.

This is a great example of a benefit of Node.js: it’s a breeze to integrate a pure JavaScript library and pre-compute the search index.

You can see Search in action at codewithhugo.com/search/?q=lunrjs.

Find the full gist at gist.github.com/HugoDF

Load up all markdown content with frontmatter

We only want to index a single directory, the “content/posts” directory, our loadPostsWithFrontMatter function will accept the full path of the posts directory.

First thing this function does it read the directory contents to get all the file names.It then reads each file and parses the frontmatter and markdown. It flattens the content and the frontmatter data into a single object. It also truncates the content to 3000 characters to avoid generating a huge (2MB+) index file.

const fs = require('fs').promises;
const {promisify} = require('util');
const frontMatterParser = require('parser-front-matter');
const parse = promisify(frontMatterParser.parse.bind(frontMatterParser));
async function loadPostsWithFrontMatter(postsDirectoryPath) {
const postNames = await fs.readdir(postsDirectoryPath);
const posts = await Promise.all(
postNames.map(async fileName => {
const fileContent = await fs.readFile(
`${postsDirectoryPath}/${fileName}`,
'utf8'
);
const {content, data} = await parse(fileContent);
return {
content: content.slice(0, 3000),
...data
};
})
);
return posts;
}

Creating the Lunr.js index

Given a list of posts, we want to use the title as a reference (more on that later), and index the title, content and tags fields.

const lunrjs = require('lunr');
function makeIndex(posts) {
return lunrjs(function() {
this.ref('title');
this.field('title');
this.field('content');
this.field('tags');
posts.forEach(p => {
this.add(p);
});
});
}

Putting it all together

The following script needs to have the previously defined JavaScript functions in scope to work, and be at the root of the Hugo project in order to read all the posts into the search index.

See the full file at gist.github.com/HugoDF/aac2e529f79cf90d2050d7183571684b.

This function actually just logs the stringified index out. To get it into a file, we could add await fs.writeFile('./path/to/index.json', JSON.stringify(index), 'utf8') or we can redirect the output of a file (which is a bit more flexible).

async function run() {
const posts = await loadPostsWithFrontMatter(`${__dirname}/content/post`);
const index = makeIndex(posts);
console.log(JSON.stringify(index));
}
run()
.then(() => process.exit(0))
.catch(error => {
console.error(error.stack);
process.exit(1);
});

Generating the index file

I personally created a static/gen folder that includes a .gitkeep file. Added the empty folder to git and then ignored it, then my Lunr.js search index generation command is:

node ./build-lunrjs-index.js > static/gen/search-index.json

You can also just stuff the search index into the root of your static folder:

node ./build-lunrjs-index.js > static/search-index.json

Or even put it in public directly:

node ./build-lunrjs-index.js > public/search-index.json

In each of these cases, be weary of trying to redirect output to a directory that doesn’t exist (especially in your continuous integration pipeline).

Consuming the Lunr.js index client-side

To consume the Lunr.js index, we just have to load it and call lunr.Index.load, as illustrated below:

fetch('/gen/search-index.json').then(function (res) {
return res.json();
}).then(function (data) {
const index = lunr.Index.load(data);
const matches = index.search(searchString);
});

A more fully featured integration might be as follows.

We want a search box (form) with a submit button and a clear link.When the page loads, we first check what the q param contains by trying to parse it as a URLSearchParams.

If it’s empty, display an information message.

If there is a search query, we load up the search index using fetch, load into into memory using lunr.Index.load and search against it.What we’ve also done before this point is generate a post title -> search result mapping using Hugo slices and a bit of JavaScript to marshal it.

Using the title -> result mapping, we display relevant search results.

<form method="get" action="">
<input id="search" name="q" type="text" />
<button type="submit" class="button">Search</button>
<a href="/search">Clear</a>
</form>
<div id="#app"></div>
<script src="https://unpkg.com/lunr/lunr.js"></script>
<!-- Generate a list of posts so we can display them -->
{{ $p := slice }}
{{ range (where .Site.RegularPages "Section" "==" "post") }}
{{ $post := dict "link" .RelPermalink "title" .Title "content" (substr .Plain 0 200) -}}
{{ $p = $p | append $post -}}
{{ end }}
<script>
const posts = JSON.parse(
 {{ $p | jsonify }}
);

const query = new URLSearchParams(window.location.search);
const searchString = query.get('q');
document.querySelector('#search').value = searchString;
const $target = document.querySelector('#app');

// Our index uses title as a reference
const postsByTitle = posts.reduce((acc, curr) => {
 acc[curr.title] = curr;
 return acc;
}, {});

fetch('/gen/search-index.json').then(function (res) {
 return res.json();
}).then(function (data) {
 const index = lunr.Index.load(data);
 const matches = index.search(searchString);
 const matchPosts = [];
 matches.forEach((m) => {
 matchPosts.push(postsByTitle[m.ref]);
 });

 if (matchPosts.length > 0) {
 $target.innerHTML = matchPosts.map(p => {
 return `<div>
 <h3><a href="${p.link}">${p.title}</a></h3>
 <p>${p.content}...</p>
 </div>`;
 }).join('');
 } else {
 $target.innerHTML = `<div>No search results found</div>`;
 }
});

You can see Search in action at codewithhugo.com/search/?q=lunrjs.

See the full gist at gist.github.com/HugoDF

unsplash-logo
N.

JavaScript Data Type Check Cheatsheet

Hugo Di Francesco — Mon, 24 Jun 2019 00:00:00 +0000

JavaScript (JS) is a lightweight, interpreted, or just-in-time compiled programming language with first-class functions.

MDN Web Docs - JavaScript

Detailed in this post are common JavaScript data type checks, pitfalls and idiomatic workarounds.

Classic JavaScript Data Type Checks

Here’s a collection of the most common data type checks in JavaScript. Whether you want to check if a variable contains a Date, a Promise, a plain old JavaScript object or an Array, it’s all here.

Everything from primitive types like number, boolean, string to detecting functions.

Check if JavaScript variable contains an object

typeof does output 'object' for objects.

It also does so for null and Arrays.

const object = {};

console.log(typeof object); // 'object'
console.log(typeof null); // 'object'
console.log(typeof []); // 'object'

console.log(object instanceof Object); // true
console.log(null instanceof Object); // false
console.log([] instanceof Object); // true

What’s more, much like in the case of Arrays, if there is inter-frame communication, it tends to share objects and arrays (see JavaScript array type check - “is array” vs object in-depth). Therefore, checking whether something is a simple object vs an instance of a class is difficult.

In JavaScript you’ll notice that everything is an Object, and when you try to access a property that doesn’t exist, it’ll fail quietly (ie. return undefined):

console.log('aaaaa'.noProperty); // undefined
console.log([].nothing); // undefined

In idiomatic JavaScript code, we leverage this property to be just defensive enough, for example if we expect an object that has a growl method, but something else might be passed in:

function safeGrowl(anything) {
  if (anything.growl) {
    anything.growl()
  }
}

safeGrowl('hello'); // nothing
safeGrowl({ growl() { console.log('Growl!') }}); // Growl!

The moral of the story is: don’t check that something is an object, check that it has the properties you need (that’s what’s called duck typing).

Check if a value is a string in JavaScript

For strings, we can use a typeof check.

Much the same as for object checks, JavaScript won’t fail loudly when you try to use something as a string that isn’t a string, it will tend to just coerce it or call .toString on it.

const string = 'Hello World';
console.log(typeof string); // 'string'

// Implicit coercion to string using templates
const helloCount = 2;
const newString = `Hello number ${helloCount} at ${new Date('2019-06-23T21:00:26.861Z')}`;

console.log(newString);
// 'Hello number 2 at Sun Jun 23 2019 22:00:26 GMT+0100 (British Summer Time)'

This works with dates, number. For arrays and other objects that don’t directly implement a toString method, I would suggest using JSON.stringify.

const myArray = ['a', 'b', 'c'];
const mySimpleObject = { key: 'value' };

console.log(`${myArray} ${mySimpleObject}`); // 'a,b,c [object Object]'
console.log(`${JSON.stringify(myArray)} ${JSON.stringify(mySimpleObject)}`)
// '["a","b","c"] {"key":"value"}'

Check if a value is a JavaScript Number/Integer

JavaScript Numbers are a bag of fun. They’ve got a similar gotcha to object checks, that’s the NaN (Not a Number) value. NaN usually is the output of trying to do arithmetic where one of the operands is not a Number.

The quirks of NaN is that it’s not equal to itself, and it’s actually a Number, just like Infinity and - Infinity

console.log(NaN == NaN); // false
console.log(NaN === NaN); // false

console.log(typeof NaN); // 'number'
console.log(typeof Infinity); // 'number'
console.log(typeof -Infinity); // 'number'
console.log(typeof 123); // 'number'

Checking that a Number is not `NaN` (Not A Number)

One NaN check would just be:

const a = NaN;

function isNotANumber(maybeNotANumber) {
  return maybeNotANumber === maybeNotANumber;
}

isNotANumber(a); // true

The recommended approach is the following, there’s a built-in Number.isNaN function:

console.log(Number.isNaN(NaN)); // true
console.log(Number.isNaN('abc')); // false
console.log(Number.isNaN(1234)); // false
console.log(Number.isNaN(123.11)); // false
console.log(Number.isNaN(true)); // false

The difference between Number.isNaN and the isNaN global is that Number.isNaN checks that the value passed in is a Number and it is NaN.

The older global isNaN function just goes for the literal check that something is not a number.

console.log(isNaN(NaN)); // true
console.log(isNaN('abc')); // true
console.log(isNaN(1234)); // false
console.log(isNaN(123.11)); // false
console.log(isNaN(true)); // false

Check if a JavaScript variable contains an Integer

To check that JavaScript variable (or value) is an integer, we can use Number.isInteger:

console.log(Number.isInteger(123)); // true
console.log(Number.isInteger(12.3)); // false
console.log(Number.isInteger(123.0)); // true

Check if a JavaScript variable contains a useable Number value

To check that we’ve got a useable input value, we should check that the type is number and that the value is not NaN:

function isValidNumber(maybeNumber) {
  return typeof maybeNumber === 'number' && !Number.isNaN(maybeNumber);
}

console.log(isValidNumber('aaaaa')); // false
console.log(isValidNumber(NaN)); // false
console.log(isValidNumber(123)); // true
console.log(isValidNumber(1.23)); // true

Check if a value is a boolean

As with JavaScript string and number data types, in JavaScript the pattern is to assume something is a boolean (or cast it to boolean) rather than checking that it’s a boolean. That’s because in JavaScript we can use logical operators with non boolean values due to the loose typing, this is usually explained through the concept of “truthiness” and “falsiness”.

When JavaScript is expecting a boolean and it is given one of the values below, it will always evaluate to “falsy”

MDN Web Docs - Falsy

The values in question (falsy values) are: false, 0, '' (or other empty string), null and undefined. Any other value will be evaluated to true.

There are some cases where false means something other than undefined, in that case, it’s possible to check that a value is falsy and a boolean by using the typeof:

console.log(typeof true); // 'boolean'
console.log(typeof false); // 'boolean'

Check if a variable contains an Array

To check if a JavaScript variable is an Array, there’s a built-in Array.isArray.

The fun gotcha with JavaScript Arrays is that they’re just objects.

console.log(([]) instanceof Object); // true
console.log(typeof []); // 'object'

A way to duck-type an Array is to use existence of a .length property. However this can be pretty weak since there’s nothing enforcing that Arrays should be the only type to have a .length property. The pattern tends to look like so:

function processList(maybeArray) {
  if (!maybeArray.length) {
    return []
  }
  return maybeArray.map(i => i); // literally copy
}

Now this code doesn’t actually check that maybeArray is an Array. It sort of does that but in the same line of code ie. !maybeArray.length, it also states that maybeArray must have a non-falsy length, ie. in the case where it is in fact an Array, it shoul also not have length 0 (must not be empty).

It’s trivial to trick the above and make it crash on .map with for example using the following data: { length: 'aaaa' }. That’s not the point, if consumers of this function are trusted, this kind of check can be fine.

Using Array.isArray however works as follows:

console.log(Array.isArray({})); // false
console.log(Array.isArray(new Map())); // false
console.log(Array.isArray(new Set())); // false

console.log(Array.isArray([])); // true
console.log(Array.isArray(new Array())); // true

For a closer look at the internals of how we check for Arrays, see JavaScript array type check - “is array” vs object in-depth. The big gotcha with built-in JavaScript data types like Array, Object and Date in JavaScript is that communicating between frames means the constructors and therefore instanceof checks don’t work.

Check if an object is an instance of a specific class/constructor function

Say you’ve got a set variable and you want to check that it’s a React Component, you can do:

import React, { Component } from 'react';

const myComp = new Component();

function isReactComponent(maybeComponent) {
  return maybeComponent instanceof Component;
}

isReactComponent(myComp);
// true

isReactComponent({});
// false

This also works with constructor functions:

function Dog (name) {
  this.name = name
}

const max = new Dog('Max');

console.log(max instanceof Dog); // true

Another interesting thing is it works all the way up the prototype chain/class hierarchy:

console.log(({}) instanceof Object); // true
console.log((new Dog) instanceof Object); // true

Check if an object is an Error

Error is just a constructor/class. So in the same way we could check for React.Component or Dog class:

function isError(maybeError) {
  return maybeError instanceof Error;
}

isError(new Error('Something went wrong')); // true
isError(new EvalError()); // true
isError(new InternalError()); // true
isError(new RangeError()); // true
isError(new ReferenceError()); // true
isError(new SyntaxError()); // true
isError(new TypeError()); // true
isError(new URIError()); // true

See more about Fundamental Objects on MDN.

Check for a valid JavaScript Date string (parseable date-string)

function isValidDateString(maybeDateString) {
  return !Number.isNaN(Number(new Date(maybeDateString)));
}

console.log(isValidDateString('abcd')); // false
console.log(isValidDateString(1234)); // true
console.log(isValidDateString('2019-06-23T22:00:26.861Z')); // true

The above function doesn’t actually check whether something is a valid string but whether it’s convertible to a valid date.

For most intents and purposes, it will catch dodgy date strings, and has the benefit of not being unreadable at the cost of allow number timestamps to be passed in. A more apt name might be isConvertibleToDate. Disallowing numbers would just be a case of adding a typeof maybeDateString === 'string'.

Check for a valid JavaScript Date

To check whether or not something is a valid, we’ll just take the same approach as checking whether it’s convertible to a date

function isValidDateObject(maybeDate) {
  return (
    typeof maybeDate === 'object' &&
    !Number.isNaN(Number(new Date(maybeDate))
  );
}

isValidDateObject('abc'); // false
isValidDateObject(1234); // false
isValidDateObject('2019-06-23T22:00:26.861Z'); // false
isValidDateObject(new Date('2019-06-23T22:00:26.861Z')); // true

You could also apply the instanceof approch:

function isValidDateObject(maybeDate) {
  return maybeDate instanceof Date;
}

isValidDateObject('abc'); // false
isValidDateObject(1234); // false
isValidDateObject('2019-06-23T22:00:26.861Z'); // false
isValidDateObject(new Date('2019-06-23T22:00:26.861Z')); // true

This has some cross-frame issues and you never know when someone might mess with the global Date to replace it with their own custom, non-standard version.

Check if a JavaScript variable is a Promise

Promise checks are done using instanceof with all the usual cross-frame or custom implementation caveats:

console.log({} instanceof Promise); // false

With Promises there’s also the issue for then-ables. Which for most intents and purposes may as well be Promises but which won’t pass our above check.

In async/await-enabled environments, you’ll also note that await-ing a function that doesn’t return a Promise doesn’t cause any unintended side-effects, the return value of the function (even if it’s not an async function), can be stored the same way as you would if you hadn’t await-ed.

Check if a JavaScript variable is a function

As mentioned on the MDN Web Docs JavaScript is a “programming language with first-class functions”. First-class functions, just means functions are treated like any other variable.

console.log(typeof (() => {})); // 'function'
console.log(typeof function () {}); // 'function'
function myFunc () {}
console.log(typeof myFunc); // 'function'

Refer to the object example to see how an idiomatic “run this function if it exists” would look.

Debugging JavaScript Data Type Issues

What does each of the following look like when it’s console.log-ed?

One of the big issues is that console.log tends to stringify whatever object it’s passed using its .toString() method. A lot of the time, a combination of pattern matching, logging out typeof and logging out a JSON.stringify-ed version of the object gives good results.

Figuring out if something is a Promise

Forgot to await a function that returns a Promise (including an async function).

You usually want to do something with the output of the Promise:

A promise that’s supposed to return a list

const fetchList = async () => ['first-item'];

async function doSomething() {
  const [firstItem] = fetchList();
}

doSomething()
// UnhandledPromiseRejectionWarning:
// TypeError: fetchList is not a function or its return value is not iterable

A promise that’s supposed to return an object

const fetchObj = async () => ({ property: 'value' });

async function doSomething() {
  const obj = fetchObj();
  console.log(obj.property);
  console.log(obj);
  console.log('done')
}

doSomething()
// undefined
// Promise {
// { property: 'value' },
// and so on

Debugging Array vs Array-like

There are a few Array-like objects in JavaScript for example arguments, NodeLists (output of document.querySelectorAll).

The first thing to do is to just log them out:

const anchors = document.querySelectorAll('a');
console.log(anchors); // { "0": {}, "1": {} }

function multiVariateFn() {
  console.log(arguments)
}

multiVariateFn(1, 2, 3); // [Arguments] { '0': 1, '1': 2, '2': 3 }

Compare those outputs to:

console.log([1, 2, 3]); // [1, 2, 3]

Here is the old-school method of converting them to regular Array-s (which means you can use Array.forEach/.map etc.):

const anchors = Array.prototype.slice.call(
  document.querySelectorAll('a'),
  0
);

function multiVariateFn() {
  const args = Array.prototype.slice.call(arguments, 0);
  return args.reverse();
}

console.log(multiVariateFn(1, 2, 3, 4)); // [4, 3, 2, 1]
console.log(multiVariateFn('a', 'b', 'c')); // ['c', 'b', 'a']

The ES6 approach would look something closer to this, they take advantage of array spread syntax and rest parameters syntax respectively.

const anchors = [...document.querySelectorAll('a')];

function multiVariateFn(...args) {
  return args.reverse();
}

console.log(multiVariateFn(1, 2, 3, 4)); // [4, 3, 2, 1]
console.log(multiVariateFn('a', 'b', 'c')); // ['c', 'b', 'a']

A more conservative approach could leverage Array.from (see Array from MDN Web Docs):

const anchors = Array.from(document.querySelectorAll('a'));

function multiVariateFn() {
  return Array.from(arguments).reverse();
}

console.log(multiVariateFn(1, 2, 3, 4)); // [4, 3, 2, 1]
console.log(multiVariateFn('a', 'b', 'c')); // ['c', 'b', 'a']

Source Materials - Further Reading

While creating this JavaScript Data Type Check guide, I took inspiration from some of the top relevant posts:

As well as the MDN Web Docs for JavaScript.

unsplash-logo
Daniel Fazio

Tailwind CSS 1.x impressions, development and production setup for static sites with Tailwind CLI and PurgeCSS CLI

Hugo Di Francesco — Mon, 17 Jun 2019 00:00:00 +0000

How to set Tailwind CSS up with a static site hosted on Netlify

See the full starter repository at github.com/HugoDF/netlify-lambda-tailwind-static-starter

Tailwind CSS is “a utility-first CSS framework for rapidly building custom designs”. I’ll be walking through my first impressions of it as well as how to leverage its CLI (and the PurgeCSS CLI) to add it to any project without a build process (eg. Webpack, Gulp).

First Impressions of Tailwind CSS

Pros

The integrated CLI tool means you don’t have to set up your own build step. I’ve found that for development, running the full tailwind build (no purging of styles), is beneficial, so much so that I’ve added it as the prestart npm script (means it runs before yarn start or npm start).

Tailwind 1.x leverages PostCSS instead of being SCSS or stylus based. Despite the massive stride forward node-sass has been for frontend tooling, the fact that it is a linked dependency can cause issues when changing Node versions or using different Operating Systems.

It’s a breath of fresh air to not have to set up node-sass, a skill which you forget as soon as you’ve got the build up and running.

Tailwind’s utility-first approach means I barely even write any CSS. I managed to quickly map my CSS knowledge onto the utility classes which makes it great for quickly gettting a prototype up. A great read on how to get over the “why would anyone do this” moment of utility classes, is Adam Wathan’s CSS Utility Classes and “Separation of Concerns” .

Once the few command line tools necessary for a productive Tailwind 1.x setup are stringed together (namely PurgeCSS) it feels great.

The copy-pastable component library is also great. Unlike Bootstrap, Foundation or even some of the more modern toolkits like Material UI or Bulma, none of the Tailwind CSS components rely on JavaScript. It’s a CSS framework after all. So the components are more of a cookbook/recipe that are meant to be copy-pasted and modified.

Tailwind 1.x pushes a pre-defined colour palette and rationalises what sizes are allowed.No more pixel-slinging, there’s just a scale: 1 2 3 4 5 6 8 10 12 16 20 24 32 40 48 56 64,you can read more about the Tailwind CSS scale in the Default spacing scale documentation.

Cons

The default bundle size is quite large, this can be offset using PurgeCSS or by configuring the build (see Controlling File Size in the Tailwind CSS documentation)

PurgeCSS CLI can be a pain to set up, and you have to whitelist liberally to get Tailwind CSS modifier utils. That’s all pretty well documented though.

The repetition involved with using a utility-class based framework like Tailwind CSS is a bit tedious to begin with.

1.x also introduced a bunch of extra places where you need to repeat yourself, all the links need to have a class="text-blue-500 hover:text-blue-800”, all the headings have to manually sized. In the long run, this is great since these are the kind of styles that would keep getting overwritten, so why not leave them unstyled from the start.

There’s no more SCSS, no more CSS even, it’s all utility classes and that can get to you.

Verdict

I’m a fan, it’s nice and orthogonal to all my other stack choices:

I can use it with an SPA setup

I can use it with static (just HTML) demos on Netlify eg. Netlify Pocket Lambda demo

I can use with a server-page setup

With the command-line tool, it’s even language agnostic. I don’t need to add npm/Node to the deployed environment, I can pre-build, use the CDN version or even check it into git.

Setting up Tailwind CSS v1.x for a static site with Yarn, Tailwind CLI and PurgeCSS CLI

Getting up and running with Tailwind CLI

yarn add --dev tailwindcss
# or
npm install --save-dev tailwindcss

Add the following to package.json.

{
  "scripts": {
    "build:css": "yarn build:tw",
    "build:tw": "tailwind build src/styles.css -o public/styles.css",
  }
}

Brutally prune CSS rules with PurgeCSS CLI

Important : This is the naive way of doing CSS purging.It doesn’t take into consideration that we’re using Tailwind CSS.Hence when using this approach, some utilities won’t work.See PurgeCSS configuration for Tailwind for the right way to do it.

yarn add --dev purgecss
# or
npm install --save-dev purgecss

Add the following to package.json.We’re leveraging npm scripts “post”-hook to run PurgeCSS against the output of the Tailwind CLI.

It works since build:css is the Tailwind CLI generation command.

We use the --css argument to point PurgeCSS to the generated styles and the --content argument to point to the HTML that we’re purging against.

The --out flag uses the same directory as the initial (pre-PurgeCSS) styles.css, which means we’re overwriting it.

{
  "scripts": {
    "postbuild:css": "purgecss --css public/styles.css --content public/index.html --out public"
  }
}

Setting up for development

For development we want to use a full Tailwind CSS build.

In order to do that, we’ll leverage the fact that we tend to run application using the start script.

Once again, we’ll leverage npm script hooks, in this case a “pre”-hook, to run a full Tailwind CSS v1.x build.

The prestart script simply calls yarn build:tw.

Add the following to your scripts:

"prestart": "yarn build:tw",

Now when you run yarn start, before the start script is run, a full Tailwind build will be run.In the case of the Netlify starter project at github.com/HugoDF/netlify-lambda-tailwind-static-starter, the start command use netlify dev ie. Netlify Dev which is supposed to run the site just as it would when it gets deployed to Netlify.

Production PurgeCSS configuration for Tailwind

As mentioned in Brutally prune CSS rules with PurgeCSS CLI, that naive approach doesn’t work.

Here’s how to set PurgeCSS CLI up properly to be Tailwind v1.x aware, it hinges on the using a Tailwind CSS specific extractor (which is just a RegEx).

We’re leveraging the extractors option as documented under PurgeCSS “Configuration File”, see the following purgecss.config.js

module.exports = {
  content: ['path/to/content.html'],
  css: ['path/to/styles.css'],
  extractors: [
    {
      extractor: {
        extract: content => content.match(/[A-z0-9-:\/]+/g)
      },
      extensions: ['html']
    }
  ]
};

And update the postbuild:css script to the following in order to use the purgecss.config.js file and still output to public directory (thereby overwriting the intiail Tailwind CLI output).

"postbuild:css": "purgecss -c purgecss.config.js -o public"

Get started with a production-ready Tailwind CSS for static sites on Netlify

See and use the full starter repository at github.com/HugoDF/netlify-lambda-tailwind-static-starter

unsplash-logo
seth schwiet

Jest exclude file/function/statement from test coverage

Hugo Di Francesco — Mon, 10 Jun 2019 00:00:00 +0000

In computer science, test coverage is a measure used to describe the degree to which the source code of a program is executed when a particular test suite runs.

Code coverage - Wikipedia

Code coverage is usually used as a quality metric for software eg. “Our code has to have 80%+ test coverage”. Gathering test coverage with Jest is as simple as using the --coverage flag on invocation.

This post goes through how to ignore files, functions and statements from coverage in Jest using configuration or istanbul pragmas. As well as reasons and limits to why/how you would do such a thing.

You can find a working examples repository at github.com/HugoDF/jest-ignore-coverage.

How does Jest even calculate coverage?

Jest uses istanbul under the hood to calculate coverage. Mostly Jest abstracts this from the end user, all you have to do in your application is call jest --coverage (and configured the appropriate coverage configuration fields). The fact that istanbul is used internally does show, for example, the documentation for coverageReporters mentions that “Any istanbul reporter can be used.”, which shows what’s actually collecting coverage data and generating the reports.

Why would I want to exclude files from coverage?

As stated by the maintainers and authors of the istanbul coverage libary:

Some branches in JS code are typically hard, if not impossible to test.Examples are a hasOwnProperty check, UMD wrappers and so on. Istanbul now has a facility by which coverage can be excluded for certain sections of code.

Istanbul - Ignore code for coverage purposes

What’s more, 100% coverage isn’t necessary or even reasonable in most cases. Some files don’t contain any (business) logic. Or they contain logic that would fail in a very obvious way (eg. a starter crashing on start).

For example the script that would bootstrap an application might bind to a port, which makes it unwieldy to test. The file that imports all the different dependencies and app.use()-es them in an Express setting would be another candidate for maybe avoiding the unit testing/dependency mocking hell.

Another class of files/functions you might want to ignore for coverage purposes are test-specific helpers. It doesn’t matter that some of them aren’t run as part of tests, as they’re not the code under test.

As with a lot of things in software, it’s about tradeoffs.

Exclude file(s) from Jest coverage by not running relevant tests using configuration

There’s a Jest configuration option testPathIgnorePatterns (see the docs for testPathIgnorePatterns)

The simplest way to configure this is through the package.json:

{
  "jest": {
    "testPathIgnorePatterns" : [
      "<rootDir>/ignore/this/path/" 
    ]
  }
}

See it in action at Exclude file(s) from Jest coverage using configuration on GitHub.

Exclude file(s) from coverage by not including it in the coverage collection configuration

As an alternative or augmentation to not running tests (as seen in “Exclude file from Jest coverage by not running relevant tests using configuration”) from Jest coverage by not including it in coverage reports, that’s controlled by the collectCoverageFrom Jest configuration option (see the docs for Jest collectCoverageFrom).

Use something like the following:

{
  "jest": {
    "collectCoverageFrom": [
      "src/**/{!(ignore-me),}.js"
    ]
  }
}

Important : make sure to wrap the ignored file’s name with ().

See it in action at Exclude file(s) from Jest coverage using configuration on GitHub.

Exclude file from Jest coverage at the file level

We can use istanbul pragmas to ignore files using the following comment at the top of any file:

/* istanbul ignore file */

See it in action at Exclude file from Jest coverage at the file level on GitHub

Exclude function from Jest coverage

/* istanbul ignore next */
function myFunc() {
  console.log(
    "Not covered but won't appear on coverage reports as such"
  );
}

See it in action at Exclude function or statement from Jest coverage on GitHub.

Exclude statement from Jest coverage

Avoid this if you can, if you’re testing some code you should probably test all of that code.

function myFunc(a) {
  /* istanbul ignore else */
  if (a) {
    // do some work
  } else {
    // do some other work
  }
}

See it in action at Exclude function or statement from Jest coverage on GitHub.

How long is a new feature/page expected to take?

Hugo Di Francesco — Sun, 09 Jun 2019 11:33:34 +0000

One of my mentees just asked me
"When working for a company, what is the expected timeline for a new feature/page?"

What would your answer be?

I've created a poll on Twitter if you're more into that: https://twitter.com/hugo__df/status/1137683451593863168?s=20

Super-powered newsletter content with Pocket and Netlify Lambda

Hugo Di Francesco — Mon, 03 Jun 2019 00:00:00 +0000

An example Netlify Lambda to fetch all “newsletter” posts from Pocket.

Pocket is an application and web service for managing a reading list of articles from the Internet. It's quite widely used and tightly integrated into the Firefox browser. I find that I use it extensively to save articles (usually about development).

For the Enterprise Node.js and JavaScript newsletter I have a “From the Web” section, which is populated from links from the web. Since most links that end up there are at one point or another stored on Pocket, I built a lambda that fetches posts tagged with “newsletter” from Pocket. I then consume that lambda from a Hugo newsletter file generator.

See the lambda code at src/lambda/newsletter.js in the repository github.com/HugoDF/pocket-newsletter-lambda.

Run it at https://pocket-newsletter-lambda.netlify.com/, or even deploy your own on Netlify.

The application is styled using TailwindCSS, you can see a starter project for that at github.com/HugoDF/netlify-lambda-tailwind-static-starter.

Pocket Fetching logic

The bulk of the Pocket-specific logic is the fetchBookmarks function, it does the following:

fetch from Pocket API using consumer key and access token
- passes state: 'all' in order to get both archived and unarchived posts
- uses tag: 'newsletter' to fetch only posts tagged with newsletter
- detailType: 'complete' means the API returns more complete data
convert the response to a flat list of { title, url, excerpts, authors } (all of those fields are strings)
return the list

See the code (full source at github.com/HugoDF/pocket-newsletter-lambda)

async function fetchBookmarks(consumerKey, accessToken) {
  const res = await axios.post('https://getpocket.com/v3/get', {
    consumer_key: consumerKey,
    access_token: accessToken,
    tag: 'newsletter',
    state: 'all',
    detailType: 'complete'
  });
  const {list} = res.data;
  // List is a key-value timestamp->entry map
  const entries = Object.values(list);
  return entries.map(
    ({
      given_title,
      given_url,
      resolved_url,
      resolved_title,
      excerpt,
      authors,
      rest
    }) => ({
      ...rest,
      title: given_title || resolved_title,
      url: given_url || resolved_url,
      excerpt,
      authors: authors
        ? Object.values(authors)
            .map(({name}) => name)
            .filter(Boolean)
            .join(',')
        : ''
    })
  );
}

Netlify Lambda request validation and body-parsing

HTTP verb and payload presence validation

The lambda only supports POST with a body, hence:

if (event.httpMethod !== 'POST') {
  return {
    statusCode: 404,
    body: 'Not Found'
  };
}

if (!event.body) {
  return {
    statusCode: 400,
    body: 'Bad Request'
  };
}

Parsing POST request bodies from form submissions and AJAX/JSON requests

We support both URL-encoded form POST requests (done eg. when JS is disabled on the demo page) and JSON requests.

The body arrives either base64 encoded (if using a URL-encoded form body request) or not. This is denoted by the isBase64Encoded flag on the event.

Parsing a base64-encoded string in Node is done using Buffer.from(event.body, 'base64').toString('utf-8).

To convert the body from URL-encoded form into an object, the following function is used, which works for POSTs with simple fields.

function parseUrlEncoded(urlEncodedString) {
  const keyValuePairs = urlEncodedString.split('&');
  return keyValuePairs.reduce((acc, kvPairString) => {
    const [k, v] = kvPairString.split('=');
    acc[k] = v;
    return acc;
  }, {});
}

Here's the functionality in the lambda:

const {
    pocket_consumer_key: pocketConsumerKey,
    pocket_access_token: pocketAccessToken
  } = event.isBase64Encoded
    ? parseUrlEncoded(Buffer.from(event.body, 'base64').toString('utf-8'))
    : JSON.parse(event.body);

If the consumer key or access token are missing we send a 400:

if (!pocketConsumerKey || !pocketAccessToken) {
  return {
    statusCode: 400,
    body: 'Bad Request'
  };
}

Sending appropriate responses on failure

We attempt to fetchBookmarks, this functionality has been broken down in “Pocket Fetching logic”.

When the Pocket API fails on a request error we want to send back that response's information to the client. If the failure can't be identified, 500. When fetchBookmarks succeeds send a 200 with data.

Thankfully when axios fails, it has a response property on the error. This means that our “Proxy back Pocket API errors” use-case and the other 2 cases are easily fulfilled with:

try {
  const bookmarks = await fetchBookmarks(pocketConsumerKey, pocketAccessToken);

  return {
    statusCode: 200,
    body: JSON.stringify(bookmarks)
  };
} catch(e) {
  if (e.response) {
    return {
      statusCode: e.response.statusCode,
      body: `Error while connecting to Pocket API: ${e.response.statusText}`
    }
  }
  return {
    statusCode: 500,
    body: e.message
  }
}

Sample response

See github.com/HugoDF/pocket-newsletter-lambda#sample-response or try out the application yourself at pocket-newsletter-lambda.netlify.com/.

A Pocket-driven newsletter in the real-world

On codewithhugo.com, the lambda doesn't read the access token and consumer key from the request. Instead it's a GET endpoints that reads the token and key from environment variables.

It's actually simpler to do that. We set POCKET_CONSUMER_KEY and POCKET_ACCESS_TOKEN in the Netlify build configuration. Then update the lambda to the following:

const {POCKET_CONSUMER_KEY, POCKET_ACCESS_TOKEN} = process.env;

// keep fetchBookmarks as is

export async function handler(event) {
  if (event.httpMethod !== 'GET') {
    return {
      statusCode: 404,
      body: 'Not Found'
    };
  }

  const bookmarks = await fetchBookmarks(POCKET_CONSUMER_KEY, POCKET_ACCESS_TOKEN);
  return {
    statusCode: 200,
    body: JSON.stringify(bookmarks)
  };
}

codewithhugo.com runs on Hugo. To generate a new newsletter file, I leverage Hugo custom archetypes (ie. a content type that has a template to generate it).

The archetype looks something like the following:

{{- $title := replace (replaceRE `[0-9]{4}-[0-9]{2}-[0-9]{2}-` "" .Name) "-" " " | title -}}
---
title: {{ $title }} - Code with Hugo
---

{{- $newsletterBookmarks := getJSON "https://codewithhugo.com/.netlify/functions/newsletter" }}
{{ range $newsletterBookmarks }}
[{{ .title }}]({{.url}}) by {{ .authors }}: {{ .excerpt }}
{{ end }}

Once the newsletter has been generated and edited, it gets added to buttondown.email, you can see the result of this approach at the Enterprise Node.js and JavaScript Archives.

unsplash-logo
Mr Cup / Fabien Barral

Avoiding recursion pitfalls: MongoDB nested query clause addition and removal

Hugo Di Francesco — Mon, 20 May 2019 00:00:00 +0000

A case-study on where recursion can be useful for enterprise Node.js applications and how to avoid its common pitfalls like RangeError: Maximum call stack size exceeded.

The full repository for this post is on GitHub: github.com/HugoDF/mongo-query-clause-modification

We’ll be implementing a solution to 2 real-world problems:

Add an $or query clause to a MongoDB query
Remove references to a field in an MongoDB query (potentially) using $or and $and

Add an $or query clause to a MongoDB query

See the final code at ./src/add-or-clause.js.

The parameters are query and orClause.

query is a MongoDB query which might or might not already contain an $or and/or $and clause.

orClause is an object containing and $or clause (it’s a fully-fledged MongoDB query in its own right) eg.

const orClause = {
  $or: [
    {createdAt: {$exists: false}},
    {createdAt: someDate}
  ]
};

There is initially just 1 thing to look out for:1. the query does not contain an $or clause2. the query contains an $or clause

When there’s no $or clause in the query

If there is no $or clause, we can simply spread our orClause query and the query parameter, ie.

const newQuery = {
  ...query,
  ...orClause
};

That is unless there’s and $and in there somewhere, in which case we want to add our orClause to the $and:

const newQuery = {
  ...query,
  $and: [...query.$and, orClause]
};

When there’s an $or clause in the query

If there is an $or clause, we can’t just overwrite it, we need to $and the two $or queries.

We should also keep existing $and clause contents which yields:

const newQuery = {
  ...queryWithoutOrRemoved,
  $and: [
    ...(query.$and || []),
    { $or: query.$or },
    orClause
  ]
};

Full solution

This is also available at ./src/add-or-clause.js.

function addOrClause(query, orClause) {
  const {$or, ...queryRest} = query;
  if ($or) {
    return {
      ...queryRest,
      $and: [...(queryRest.$and || []), {$or}, orClause]
    };
  }

  if (queryRest.$and) {
    return {
      ...queryRest,
      $and: [...queryRest.$and, orClause]
    };
  }

  return {
    ...query,
    ...orClause
  };
}

module.exports = addOrClause;

Corresponding Test Suite

We can observe how the different cases map pretty directly to test cases.

const addOrClause = require('./add-or-clause');

test('should add the passed or clause if no $or on the current query', () => {
  const orClause = {$or: [{myField: 'value'}, {myField: null}]};
  const query = {foo: 'bar'};
  expect(addOrClause(query, orClause)).toEqual({
    $or: [{myField: 'value'}, {myField: null}],
    foo: 'bar'
  });
});
describe('when the query already has an $or', () => {
  test('should add the passed or clause to and $and that also contains the current query', () => {
    const orClause = {$or: [{myField: 'value'}, {myField: null}]};
    const query = {$or: [{foo: 'bar'}, {foo: {$exists: false}}]};
    expect(addOrClause(query, orClause)).toEqual({
      $and: [
        {$or: [{foo: 'bar'}, {foo: {$exists: false}}]},
        {
          $or: [{myField: 'value'}, {myField: null}]
        }
      ]
    });
  });
  describe('when the query has an $and', () => {
    test('should keep the $and, add the $or and the current query', () => {
      const orClause = {$or: [{myField: 'value'}, {myField: null}]};
      const query = {
        $or: [{hello: 'world'}],
        $and: [{foo: 'bar'}, {bar: 'baz'}]
      };
      expect(addOrClause(query, orClause)).toEqual({
        $and: [
          {foo: 'bar'},
          {bar: 'baz'},
          {$or: [{hello: 'world'}]},
          {$or: [{myField: 'value'}, {myField: null}]}
        ]
      });
    });
  });
});
describe('when the query has an $and query', () => {
  test('should add the new or clause to the $and', () => {
    const orClause = {$or: [{myField: 'value'}, {myField: null}]};
    const query = {$and: [{foo: 'bar'}, {bar: 'baz'}]};
    expect(addOrClause(query, orClause)).toEqual({
      $and: [
        {foo: 'bar'},
        {bar: 'baz'},
        {$or: [{myField: 'value'}, {myField: null}]}
      ]
    });
  });
});

Remove references to a field in an MongoDB query (potentially) using $or and $and

See the full solution at ./src/remove-field-references.js.

In this case we’re creating a function that takes 2 parameters: query (MongoDB query as above) and fieldName (name of the field we want to remove references to).

Remove top-level fields

The simplest thing to do is remove references to the field at the top-level of the object.

We can create a simple omit function using destructuring and recursion

const omit = (obj, [field, ...nextFields]) => {
  const {[field]: ignore, ...rest} = obj;
  return nextFields.length > 0 ? omit(rest, nextFields) : rest;
};

And use it:

const newQuery = omit(query, [fieldName]);

Remove fields in any $or clause

To remove fields in an $or clause (which is a fully-fledged query) is as simple as taking the $or value (which is an array) and running a recursion of the function onto it.

This will remove fields at the top-level of the $or sub-queries and in nest $or fields’ sub-queries.

We want to make sure to remove empty $or sub-queries, since { $or: [{ }, {}]} is an invalid query.

We default the query’s $or to an empty array and check length before spreading it back into the newQuery. This is because { $or: [] } is an invalid query.

We’re also careful to remove the top-level $or when spreading filteredTopLevel so that if the new $or is an empty array, the old $or is ommitted.

function removeFieldReferences (query, fieldName) {
  const filteredTopLevel = omit(query, [fieldName]);

  const newOr = (filteredTopLevel.$or || [])
    .map(q => removeFieldReferences(q, fieldName))
    .filter(q => Object.keys(q).length > 0);

  return {
    ...omit(filteredTopLevel, ['$or']),
    ...(newOr.length > 0 ? {$or: newOr} : {})
  };
}

Remove fields in any $and clause

The rationale for the $and solution is the same as for the $or solution.

We recurse and check that we’re not generating an invalid query by omitting empty arrays and objects:

function removeFieldReferences (query, fieldName) {
  const filteredTopLevel = omit(query, [fieldName]);

  const newAnd = (filteredTopLevel.$and || [])
    .map(q => removeFieldReferences(q, fieldName))
    .filter(q => Object.keys(q).length > 0);

  return {
    ...omit(filteredTopLevel, ['$and']),
    ...(newAnd.length > 0 ? {$and: newAnd} : {})
  };
}

Check that we’re not likely to bust the stack

The actual implementation has a maxDepth 3rd parameter defaulted to 5.

When maxDepth is equal to 0, we return the query without any treatment (arguably we should run the top-level filter).

On recursive calls to removeFieldReferences we pass (q, fieldName, maxDepth - 1) so that we’re not going any deeper than we need to by accident.

This avoids RangeError: Maximum call stack size exceeded.

Final Implementation

This is also available at ./src/remove-field-references.js.

const omit = (obj, [field, ...nextFields]) => {
  const {[field]: ignore, ...rest} = obj;
  return nextFields.length > 0 ? omit(rest, nextFields) : rest;
};

function removeFieldReferences(query, fieldName, maxDepth = 5) {
  if (maxDepth <= 0) {
    return query;
  }

  const filteredTopLevel = omit(query, [fieldName]);

  const newOr = (filteredTopLevel.$or || [])
    .map(q => removeFieldReferences(q, fieldName, maxDepth - 1))
    .filter(q => Object.keys(q).length > 0);

  const newAnd = (filteredTopLevel.$and || [])
    .map(q => removeFieldReferences(q, fieldName, maxDepth - 1))
    .filter(q => Object.keys(q).length > 0);

  return {
    ...omit(filteredTopLevel, ['$or', '$and']),
    ...(newOr.length > 0 ? {$or: newOr} : {}),
    ...(newAnd.length > 0 ? {$and: newAnd} : {})
  };
}

module.exports = removeFieldReferences;

Corresponding Test Suite

We can observe how the different cases map pretty directly to test cases.

const removeFieldReferences = require('./remove-field-references');

test('should remove top-level fields', () => {
  const query = {
    hello: 'value'
  };
  const fieldName = 'hello';
  expect(removeFieldReferences(query, fieldName).hello).toBeUndefined();
});
test('should return passed query when maxDepth is hit (avoids busting the stack by default)', () => {
  const query = {
    hello: 'value'
  };
  const fieldName = 'hello';
  expect(removeFieldReferences(query, fieldName, 0)).toEqual(query);
});
test('should remove references to the field in top-level $or queries', () => {
  const query = {
    $or: [
      {hello: 'value', otherField: 'not-related'},
      {hello: 'othervalue', otherField: 'even-less-related'}
    ]
  };
  const fieldName = 'hello';
  expect(removeFieldReferences(query, fieldName)).toEqual({
    $or: [{otherField: 'not-related'}, {otherField: 'even-less-related'}]
  });
});
test('should remove $or clauses where the query becomes empty on omission of a field', () => {
  const query = {
    $or: [{hello: 'value'}, {otherField: 'not-related'}]
  };
  const fieldName = 'hello';
  expect(removeFieldReferences(query, fieldName)).toEqual({
    $or: [{otherField: 'not-related'}]
  });
});
test('should remove references to field in top-level queries inside of $and', () => {
  const query = {
    $and: [
      {hello: 'value', otherField: 'value'},
      {hello: 'other-value', otherField: 'value'}
    ]
  };
  const fieldName = 'hello';
  expect(removeFieldReferences(query, fieldName)).toEqual({
    $and: [{otherField: 'value'}, {otherField: 'value'}]
  });
});
test('should remove $and clause if all queries end up filtered out', () => {
  const query = {
    foo: 'bar',
    $and: [{hello: 'value'}, {hello: 'other-value'}]
  };
  const fieldName = 'hello';
  expect(removeFieldReferences(query, fieldName)).toEqual({foo: 'bar'});
});
test('should remove references to field in nested $or inside of $and', () => {
  const query = {
    $and: [
      {
        $or: [{hello: 'value'}, {hello: null}]
      },
      {otherField: 'not-related'}
    ]
  };
  const fieldName = 'hello';
  expect(removeFieldReferences(query, fieldName)).toEqual({
    $and: [{otherField: 'not-related'}]
  });
});

unsplash-logo
Tine Ivanič

Read and parse POST/PATCH/PUT request JSON or form body with Express and no dependencies

Hugo Di Francesco — Sat, 11 May 2019 00:00:00 +0000

When asked to handle data in a request body, developers who have used Express (the “Fast, unopinionated, minimalist web framework for Node.js”) before, reach for the body-parser library.

What they might not know is that body-parse is a dependency of Express and its main JSON parsing and url encoded body parsing functionality is exposed as express.json() and express.urlencoded(). A middleware for parsing JSON request bodies built-into Express.

Note: express.json and express.urlencoded exist in Express 4.16+

The global express.json() middleware is not to be confused with the res.json() function which sends back a body as JSON (and sets the content format headers to JSON).

The code for json bodies is at https://codesandbox.io/s/olrn6x3n19?fontsize=14, you can view the app at https://olrn6x3n19.sse.codesandbox.io/.

The code for URL encoded form bodies is at https://codesandbox.io/s/6njqzmyw4k?fontsize=14, you can test it out at https://6njqzmyw4k.sse.codesandbox.io/.

Real(ish) world usage in projects, you can also find more Express posts on Code with Hugo

express.urlencoded: https://github.com/HugoDF/express-nunjucks-tailwind/blob/master/server.js
express.json: https://github.com/HugoDF/express-postgres-starter/blob/master/server.js

Parsing JSON bodies

Drop-in example

Here is an example app that reflects the request POST body in the response:

const express = require('express')
const app = express()

app.use(express.json())
app.post(
  '/test',
  (req, res) => res.json(req.body)
)

const PORT = process.env.PORT || 3000
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`)
})

You can see it running at https://olrn6x3n19.sse.codesandbox.io/, test it using:

curl --request POST \
  --url https://olrn6x3n19.sse.codesandbox.io/test \
  --header 'content-type: application/json' \
  --data '{
    "json-parsing": "just with Express",
    "no": "body-parser"
}'

It will output:

{"json-parsing":"just with Express","no":"body-parser"}

Which is exactly what we sent in the --data property of the curl request.

Extended configuration options

You can pass options into it like so (all the values are the default values for these options):

app.use(express.json({
  inflate: true,
  limit: '100kb',
  reviver: null,
  strict: true,
  type: 'application/json',
  verify: undefined
}))

The full API docs for express.json are at expressjs.com/en/api.html#express.json.

A run-through of the options follows.

inflate controls whether or not to handle compressed/deflated request bodies. When it’s set to false, compressed/deflated bodies will get rejected.

limit controls the maximum body size. It can be either a number of bytes or a string which is compatible with the bytes library.

strict is about locking JSON.parse down to just objects and arrays. If true, only JSON.stringify-ed objects and arrays will be allowed, if false, anything that JSON.parse accepts will be parsed.

type controls which content-type the middleware will attempt to parse. The value for this option can be a string, an array of strings, or a function. Content-type wildcards are supported to some extent since string(s) are passed to the type-is library.

verify is an optional function with verify(req, res, buf, encoding) signature. buf is a Buffer containing the raw request body. verify can be used to abort parsing by throwing an error.

Parsing URL encoded form bodies

In the same way we used express.json we can use express.urlencoded.

Drop-in example

We pass extended: false to avoid a warning.

const express = require('express')
const app = express()

app.use(express.urlencoded({ extended: false }))
app.post(
  '/test',
  (req, res) => res.json(req.body)
)

const PORT = process.env.PORT || 3000
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`)
})

You can see it running at https://6njqzmyw4k.sse.codesandbox.io/, test it using the form on the page.

Extended configuration options

You can pass options into express.urlencoded like so (all the values are the default values for these options):

app.use(express.json({
  extended: true,
  inflate: true,
  limit: '100kb',
  parameterLimit: 1000,
  type: 'application/x-www-form-urlencoded',
  verify: undefined
}))

The full API docs for express.json are at expressjs.com/en/api.html#express.urlencoded.

A run-through of the options follows.

extended pretty much a toggle between the qs (when true) and querystring (when false) libraries. qs allows for rich objects and arrays to be encoded, querystring does not. Keep this as false for simple forms (all key-value pairs) and true when you’re sending arrays/maps of values.

inflate controls whether or not to handle compressed/deflated request bodies. When it’s set to false, compressed/deflated bodies will get rejected.

limit controls the maximum body size. It can be either a number of bytes or a string which is compatible with the bytes library.

parameterLimit controls the maximum number of fields that we’ll attempt to parse from the url encoded form body.

verify is an optional function with verify(req, res, buf, encoding) signature. buf is a Buffer containing the raw request body. verify can be used to abort parsing by throwing an error.

More about body-parser and other body-parsing libraries

This means we don’t need to install body-parser to load up most of our bodies. Express’ built-in JSON and URL encoded form body parsing covers the majority of use cases. What we might need a library for is multipart bodies, there are alternative libraries to handle that use-case (usually for file upload).

There are still some very specific cases where body-parser might still be necessary (see the docs at github.com/expressjs/body-parser):

unsplash-logo
Mahir Uysal

Jest assert over single or specific argument/parameters with .toHaveBeenCalledWith and expect.anything()

Hugo Di Francesco — Mon, 29 Apr 2019 00:00:00 +0000

With Jest it’s possible to assert of single or specific arguments/parameters of a mock function call with .toHaveBeenCalled/.toBeCalled and expect.anything().

The full example repository is at github.com/HugoDF/jest-specific-argument-assert, more specifically lines 17-66 in the src/pinger.test.js file.

You can use expect.anything() to ignore certain parameters that a mock Jest function is called with, see the following:

test('calls getPingConfigs with right accountId, searchRegex', async () => {
  await pinger(1);
  expect(mockPingConfig).toHaveBeenCalledWith(
    1,
    expect.anything(),
    expect.anything(),
    new RegExp('.*')
  );
});

Read on for more details of the code under test and why one would use such an approach.

The code under test follows module boundaries similar to what is described in An enterprise-style Node.js REST API setup with Docker Compose, Express and Postgres. Specifically a 3-tier (Presentation, Domain, Data) layering, where we’ve only implemented the domain and (fake) data layers.

Code under test that warrants specific parameter/argument assertions

The code under test is the following (see the full src/pinger.js file on GitHub), only relevant code has been included to make it obvious what problem we’ll be tackling with Jest mocks, .toHaveBeenCalled and expect.anything().

// Half-baked implementation of an uptime monitor
const { getPingConfigs } = require('./pingConfig');

async function getUrlsForAccount(accountId, offset, limit, searchRegex) {
  const configs = await getPingConfigs(accountId, offset, limit, searchRegex);
  // return configs.map(conf => conf.url);
}

async function pinger(accountId, { offset = 0, limit = 50 } = {}, search) {
  const searchRegex = search
    ? new RegExp(search.split(' ').join('|'))
    : new RegExp('.*');
  const urls = await getUrlsForAccount(accountId, offset, limit, searchRegex);
}

module.exports = pinger;

The only call going outside the module’s private context is getPingConfigs(accountId, offset, limit, searchRegex). This is why the assertion is going to be on the getPingConfigs mock that we’ve set with jest.mock('./pingConfig', () => {}) (see the full src/pinger.test.js code on GitHub).

Discovering orthogonality in code under test

We can also see that there’s orthogonal functionality going on. Namely:

passing of accountId
computing/defaulting/passing of a search regex
defaulting/passing of offset/limit

Issues with exhaustive test cases for orthogonal functionality

All our tests will center around the values getPingConfigs is called with (using .toHaveBeenCalledWith assertions).

Let’s create some tests that don’t leverage expect.anything(), in every call, we’ll specify the value each of the parameters to getPingConfigs: accountId, offset, limit and searchRegex.

Permutations, (Y denotes the variable passed to pinger is set, N that it is not).

accountId	offset	limit	search	single-word search
Y	N	N	Y	Y
Y	N	N	Y	N
Y	N	Y	N	N/A
Y	Y	Y	N	N/A
Y	N	N	Y	Y
Y	N	N	Y	N
Y	Y	N	Y	Y
Y	Y	N	Y	N
Y	Y	Y	Y	Y
Y	Y	Y	Y	N

Each of the above permutations should lead to different test cases if we have to specify each of the parameters/arguments in the assertion on the getPingConfigs call.

The enumeration we’ve done above would result in 10 test cases.

Creating test cases for orthogonal functionality

It turns out the following cases cover the same logic in a way that we care about:

on search
1. if search is not set, pinger should call with the default searchRegex
2. if search is set and is single word (no space), pinger should call with the correct searchRegex
3. if search is set and is multi-work (spaces), pinger should call with the correct searchRegex
on limit/offset
1. if limit/offset are not set, pinger should call with default values
2. if limit/offset are set, pinger should call with passed values

Notice how the assertions only concern part of the call, which is where expect.anything() is going to come handy as a way to not have to assert over all the parameters/arguments of a mock call at the same time.

Specific parameter asserts on a mock function call

The following implements the test cases we’ve defined in “Creating test cases for orthogonal functionality”:

describe('without search', () => {
  test('calls getPingConfigs with right accountId, searchRegex', async () => {
    await pinger(1);
    expect(mockPingConfig).toHaveBeenCalledWith(
      1,
      expect.anything(),
      expect.anything(),
      new RegExp('.*')
    );
  });
});
describe('offset, limit', () => {
  test('calls getPingConfigs with passed offset and limit', async () => {
    await pinger(1, { offset: 20, limit: 100 });
    expect(mockPingConfig).toHaveBeenCalledWith(
      1,
      20,
      100,
      expect.anything()
    );
  });
  test('calls getPingConfigs with default offset and limit if undefined', async () => {
    await pinger(1);
    expect(mockPingConfig).toHaveBeenCalledWith(1, 0, 50, expect.anything());
  });
});
describe('search', () => {
  describe('single-word search', () => {
    test('calls getPingConfigs with right accountId, searchRegex', async () => {
      await pinger(1, {}, 'search');
      expect(mockPingConfig).toHaveBeenCalledWith(
        1,
        expect.anything(),
        expect.anything(),
        new RegExp('search')
      );
    });
  });
  describe('multi-word search', () => {
    test('calls getPingConfigs with right accountId, searchRegex', async () => {
      await pinger(1, {}, 'multi word search');
      expect(mockPingConfig).toHaveBeenCalledWith(
        1,
        expect.anything(),
        expect.anything(),
        new RegExp('multi|word|search')
      );
    });
  });
});

DEV Community: Hugo Di Francesco

Celebrating the publication of "Professional JavaScript" with the Dev.to family

Yarn Workspaces: monorepo management without Lerna for applications and coding examples

Yarn Workspaces vs Lerna

Set up Yarn Workspaces

Bootstrapping the monorepo

Managing your monorepo with yarn workspace and yarn workspaces commands

Run commands in a single package

Run commands in all packages

Jest Full and Partial Mock/Spy of CommonJS and ES6 Module Imports

For Context: types of imports

Intercepting imports

The CommonJS case

ES Modules default export

ES Modules named export

Spying/Stubbing calls to internal module functions

CommonJS

A module where internal functions can’t be mocked

A module where internal function can be mocked

Mocking/Spying the internal function

ES Modules

Difficulty of Named exports

Unmockeable modules with default exports

Mock/Spy setup with ESM

Mocking internals is the same with ESM/CommonJS

Spy on imports or mock part of a module by “referencing the module”

CommonJS: Spy import/mock part of a module with Jest

ES6 Modules: Spy import/mock part of a module with Jest

Default exports

Named exports + “import * as alias from ‘module-name’”

Further Reading

Add Search to a Hugo site with Lunr.js and Node.js

Load up all markdown content with frontmatter

Creating the Lunr.js index

Putting it all together

Generating the index file

Consuming the Lunr.js index client-side

JavaScript Data Type Check Cheatsheet

Classic JavaScript Data Type Checks

Check if JavaScript variable contains an object

Check if a value is a string in JavaScript

Check if a value is a JavaScript Number/Integer

Checking that a Number is not NaN (Not A Number)

Check if a JavaScript variable contains an Integer

Check if a JavaScript variable contains a useable Number value

Check if a value is a boolean

Check if a variable contains an Array

Check if an object is an instance of a specific class/constructor function

Check if an object is an Error

Check for a valid JavaScript Date string (parseable date-string)

Check for a valid JavaScript Date

Check if a JavaScript variable is a Promise

Check if a JavaScript variable is a function

Debugging JavaScript Data Type Issues

Figuring out if something is a Promise

A promise that’s supposed to return a list

A promise that’s supposed to return an object

Debugging Array vs Array-like

Source Materials - Further Reading

Tailwind CSS 1.x impressions, development and production setup for static sites with Tailwind CLI and PurgeCSS CLI

First Impressions of Tailwind CSS

Pros

Cons

Verdict

Setting up Tailwind CSS v1.x for a static site with Yarn, Tailwind CLI and PurgeCSS CLI

Getting up and running with Tailwind CLI

Brutally prune CSS rules with PurgeCSS CLI

Setting up for development

Production PurgeCSS configuration for Tailwind

Get started with a production-ready Tailwind CSS for static sites on Netlify

Jest exclude file/function/statement from test coverage

How does Jest even calculate coverage?

Why would I want to exclude files from coverage?

Exclude file(s) from Jest coverage by not running relevant tests using configuration

Exclude file(s) from coverage by not including it in the coverage collection configuration

Exclude file from Jest coverage at the file level

Exclude function from Jest coverage

Exclude statement from Jest coverage

Further Reading

How long is a new feature/page expected to take?

Managing your monorepo with `yarn workspace` and `yarn workspaces` commands

Checking that a Number is not `NaN` (Not A Number)