Forem: Albert Alises

Create an Interactive Bash Command for searching and checking out Git Branches on the Terminal using fzf

Albert Alises — Sat, 25 Apr 2020 15:32:49 +0000

✏️ Cover art by Michael Rayback on Dribble

Git is an essential and powerful tool for any software developer. As part of your developer workflow, you might find yourself juggling between different projects and features all the time.

Given so, it's very hard to keep track of all the names of the branches between projects, especially when coming back to it after some time. So one common cumbersome procedure is looking up the name of the branch you want to get on that specific project and git checkout to it.

To achieve so, you first need to get all the branch names of the current project. Fortunately for us, git has a command for this, for-each-ref. What it does is iterate over all the references, which is a readable name that points to the SHA-1 ids of git artifacts (e.g commits), given a pattern. For example, getting refs/heads returns a list of all the references of the head commits for each branch.

You can iterate on these references to print all the branches on the terminal by using the following command:

git for-each-ref --sort='authordate:iso8601' --format='%(authordate:relative)%09%(refname:short)' refs/heads

Figure 1: command for showing all the git branches ordered by descendent author-date

Of course, you can format and sort the results however you like. The next step would be to be able to interact with that list of branches, like selecting one, copying one, searching, and/or filtering the results.

A pretty useful command for that is the well-known grep, which allows us to find patterns in the results. For example, we could chain the output of the branches command to grep pattern to search for branches that match the pattern.

I want to only see the branches which are prefixed with fix because I want to come back to fix that pesky bug? no problem, git branches | grep fix would do the filtering (pst, adding an alias to the branches command is pretty useful). Then you can copy the branch name and check out to it

... But what if we want to interactively filter the branches and navigate through them, as well as binding keyboard commands to actions? (to, for example, check out to a branch using enter!)... you can easily do that with Fzf.

Introducing Fzf

Fzf is a grep on steroids. According to the description, it is a general-purpose command-line fuzzy finder.

junegunn / fzf

🌸 A command-line fuzzy finder

^{Special thanks to:}

Warp is a modern, Rust-based terminal with AI built in so you and your team can build great software, faster.

^{Visit warp.dev to learn more.}

fzf is a general-purpose command-line fuzzy finder.

It's an interactive filter program for any kind of list; files, command history, processes, hostnames, bookmarks, git commits, etc. It implements a "fuzzy" matching algorithm, so you can quickly type in patterns with omitted characters and still get the results you want.

Highlights

📦 Portable — Distributed as a single binary for easy installation
⚡ Blazingly fast — Highly optimized code instantly processes millions of items
🛠️ Extremely versatile — Fully customizable via an event-action binding mechanism
🔋 Batteries included — Includes integration with bash, zsh, fish, Vim, and Neovim

Sponsors ❤️

I would like to thank all the sponsors of this project who make it possible for me to continue to improve fzf.

If…

View on GitHub

Fzf grabs the output of any command, being it a list, processes, text... and lets you search and filter these results interactively and navigate through them. You can also assign key bindings to commands on your search.

With it, we can search and navigate through any directory easily and look for files, also adding some key bindings e.g opening the file in vscode when clicking enter and copying the filename path with tab.

ls | fzf --preview 'bat --style=numbers --color=always {}' --bind 'enter:execute(code {}),tab:execute-silent(echo {} | pbcopy)+abort' | head -100

Figure 2: command for searching and navigating through a directory with key bindings using fzf

Figure 3: output of the ls command using fzf

The above example uses bat instead of cat for previewing files, as it includes some nice features like syntax highlighting and also shows modifications on files by integrating with git.

sharkdp / bat

A cat(1) clone with wings.

A cat(1) clone with syntax highlighting and Git integration

Key Features • How To Use • Installation • Customization • Project goals, alternatives
[English] [中文] [日本語] [한국어] [Русский]

Syntax highlighting

bat supports syntax highlighting for a large number of programming and markup languages:

Git integration

bat communicates with git to show modifications with respect to the index (see left side bar):

Show non-printable characters

You can use the -A/…

View on GitHub

Creating the interactive branch navigator with Fzf

With the fzf command in place, we can pipe our git branches command [Fig. 1] to the fzf part of [Fig. 2] with some tweaking of the key bindings, and that will allow us to filter, copy and check out branches, just like that:

git for-each-ref --sort='authordate:iso8601' --format='%(authordate:relative)%09%(refname:short)' refs/heads | fzf --tac --bind 'enter:execute(echo {} | rev | cut -f1 | rev | xargs git checkout)+abort,tab:execute-silent(echo {} | rev | cut -f1 | rev | pbcopy)+abort'

Figure 4: command for interactively searching git branches,checking them out by pressing `enter` and copying the branch name by using `tab`

You can then bind the command to some git alias in ~/.gitconfig, I have it assigned to git brs.

Figure 5: assigning a git alias for the command

Fzf includes numerous built-in key bindings as exiting with escape or navigating with scrolling/arrows, to name a couple. Try extending the command by adding more key bindings that fit your workflow!

Here's a short example of the command in action:

Figure 6: interactive branch navigation command example on the terminal

That's it! ✨

And you, what other amazing fzf commands do you use, or would you create to improve your development workflow?

Dealing with Asynchrony when Writing End-To-End Tests with Puppeteer + Jest

Albert Alises — Fri, 21 Sep 2018 09:35:01 +0000

In this article we present an overview on how to deal with asynchrony when performing end-to-end tests, using Puppeteer as a web scraper and Jest as an assertion library. We will learn how to automate user action on the browser, wait for the server to return data and for our application to process and render it, to actually retrieving information from the website and comparing it to the data to see if our application actually works as expected for a given user action.

So you got your wonderful web application up and running, and the time for testing has come.... There are many types of test, from Unit tests where you test the individual components that compound your application, to Integration tests where you test how these components interact with eachother. In this article we are gonna talk about yet another type of tests, the End-To-End (e2e) tests.

End-to-end tests are great in order to test the whole application as a user perspective. Tha means testing that the outcome, behavior or data presented from the application is as expected for a given user interaction with it. They test from the front-end to the back-end, treating the application as a whole and simulating real case scenarios. Here it is a nice article talking about what e2e tests are and their importance.

To test javascript code, one of the most common frameworks for assertions is Jest, which allows you to perform all kinds of comparisons for your functions and code, and even testing React components. In particular, to perform e2e tests, a fairly recent tool, Puppeteer, comes to the rescue. Basically it is a web scraper based on Chromium. According to the repo, it is a "Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol".

It provides some methods so you can simulate the user interaction on a browser via code, such as clicking elements, navigating through pages or typing on a keyboard. As having a highly trained monkey perform real case tasks on your application 🐒

You can find the github repos of both testing libraries here:

jestjs / jest

Delightful JavaScript Testing.

🃏 Delightful JavaScript Testing

👩🏻‍💻 Developer Ready: A comprehensive JavaScript testing solution. Works out of the box for most JavaScript projects.

🏃🏽 Instant Feedback: Fast, interactive watch mode only runs test files related to changed files.

📸 Snapshot Testing: Capture snapshots of large objects to simplify testing and to analyze how they change over time.

See more on jestjs.io

Getting Started

Install Jest using yarn:

yarn add --dev jest

Or npm:

npm install --save-dev jest

Note: Jest documentation uses yarn commands, but npm will also work. You can compare yarn and npm commands in the yarn docs, here.

Let's get started by…

View on GitHub

puppeteer / puppeteer

JavaScript API for Chrome and Firefox

Puppeteer

Puppeteer is a JavaScript library which provides a high-level API to control Chrome or Firefox over the DevTools Protocol or WebDriver BiDi Puppeteer runs in the headless (no visible UI) by default

Get started | API | FAQ | Contributing | Troubleshooting

Installation

npm i puppeteer # Downloads compatible Chrome during installation.
npm i puppeteer-core # Alternatively, install as a library, without downloading Chrome.

Example

import puppeteer from 'puppeteer';
// Or import puppeteer from 'puppeteer-core';
// Launch the browser and open a new blank page
const browser = await puppeteer.launch();
const page = await browser.newPage();

// Navigate the page to a URL.
await page.goto('https://developer.chrome.com/');

// Set screen size.
await page.setViewport({width: 1080, height: 1024});

// Type into search box.
await page

…

View on GitHub

Given so, the Puppeteer + Jest become has become a nice, open source way of testing web applications, by opening the application on the headless browser provided by puppeteer and simulating user input and/or interaction, and then checking that the data presented and the way our application reacts to the different actions is as expected with Jest.

In this article we will not cover the whole workflow of testing with puppeteer + jest (such as installing, or setting the main structure of your tests, or testing forms), but focus on one of the biggest things that we have to take into account when doing so: Asynchrony.

🤘 But hey, here you have a great tutorial on how to test with Puppeteer + Jest, to get you started.

Because almost all of the web applications contain indeed some sort of asynchrony. Data is retrieved from the back-end, and that data is then rendered on screen. However, Puppeteer performs all the operations sequentially, so... how can we tell him to wait until asynchronous events have happened?

Figure 1: I feel you, but sometimes you have to wait just a little bit for everything to be rendered and ready, so your e2e tests do not crash and burn

Puppeteer offers you a way to wait for certain things to happen, using the waitFor functions available for the Page class. The changes you can track are visual changes that the user can observe. For instance you can see when something in your page has appeared, or has changed color, or has disappeared, as a result of some asynchronous call. Then one would compare these changes to be what you would expect from the interaction, and there you have it. How does it work?

Waiting, Waiting, Waiting...⏰

The waitFor function set in Puppeteer helps us deal with asynchrony. As these functions return Promises, usually the tests are performed making use of the async/await ES2017 feature. These functions are:

waitForNavigation

await page.waitForNavigation({waitUntil: "networkidle2"});

Whenever a user action causes the page to navigate to another route, we sometimes have to wait a little bit before all the content is loaded. For that we have the waitForNavigation function. it accepts a options object in where you can set a timeout (in ms), or waitUntil some condition is met. The possible values of waitUntil are (according to the wonderful puppeteer documentation):

load (default): consider navigation to be finished when the load event is fired.
domcontentloaded: consider navigation to be finished when the DOMContentLoaded event is fired.
networkidle0: consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
networkidle2: consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

Tipically, you will want to wait until the whole page is loaded ({waitUntil: load}), but that does not guarantee you that everything is operative. What you can do is wait for a specific DOM element to appear that assures you that the whole page is loaded. you can do that with the following function:

waitForSelector

This function waits for a specific CSS selector to appear, indicating that the element it matches to is on the DOM.

await page.waitForSelector("#create-project-button");

await page.goto("https://www.example.com",{waitUntil: "load"});
await page.click("#show-profileinfo-button"); //Triggers a navigation

/* 
We can either wait for the navigation or wait until a selector that indicates 
that the next page is operative appears
*/
await page.waitForNavigation({waitUntil: "load"});
await page.waitForSelector("#data-main-table");

waitForFunction

The last one waits for some function to return true in order to proceed. It is commonly used to monitor some property of a selector. It is used when the selector is not appearing on the DOM but some property of it changes (so you cannot wait for the selector because it is already there on the first place). It accepts a string or a closure as arguments.

For example, you want to wait until a certain message changes. The testing would be performed by first getting the message using the evaluate() Puppeteer function. Its first parameter is a function which is evaluated in the browser context (as if you were typing into the Chrome console).We then perform the asynchronous operations that change the message (clicking a button or whatever 🖱🔨), and then waiting for the message to change.

const previousMessage = await page.evaluate( () => document.querySelector('#message').innerHTML);

//Async behaviour...

await page.waitForFunction(`document.querySelector('#message').innerHTML !== ${previousMessage}`); //Wait until the message changes

Using these waitFor functions we can detect when something in our page changes after an async operation, now we just need to retrieve the data we want to test.

Retrieving data from selectors after an Async operation

Once we have detected the changes caused by our asynchronous code, we tipically want to extract some data from our application that we can later compare to the expected visual result from a user interaction. We do that using evaluate() .The most common cases that you face when retrieving data are:

- Checking that a DOM element has appeared

A pretty common case is checking that a given element has been rendered on the page, hence appearing on the DOM. For instance, after saving a post, you should find it in the saved posts section. Navigating there and querying if indeed the DOM element is there is the basic type of data that we can assert (as a boolean assertion).

Find below an example of checking if a given post with an id post-id, where the id is a number we know, is present on the DOM. First we save the post, we wait for the post to be saved, go to the saved posts list/route and see that the post is there.

const id = '243';

await page.click(`#post-card-${id} .button-save-post`);

//The class could be added when the post is saved (making a style change on the button)
await page.waitForSelector(`#post-card-${id} .post-saved`);
await page.click('#goto-saved-posts-btn');
await page.waitForNavigation();


const post = await page.evaluate(id => {
    return document.querySelector(`#post-${id}`) ? true : false
},id);

expect(post).toEqual(true);

In there, we can observe a couple of things.

The aforemenctioned need to have unique id's for the tested elements. Given so, querying the selector is way easier and we do not need to do nested queries that get the element based on its position on the DOM (Hey, get me the first tr element from the first row of that table 🙋🏼).
We see how we can pass arguments to the evaluate function and use it to interpolate variables into our selectors. As the fucntion is being evaluated in another scope, you need to bind the variables from node to that new scope, and you can do that via that second parameter.

- Checking for matching property values (e.g innerHTML, option...)

Now imagine that instead of checking that an element is on the DOM, you actually want to check if the list of saved posts rendered on the page actually are the posts you have saved. That is, you want to compare an array of strings with the post names, e.g ["post1,"post2"], with the saved posts of a user (which you can know beforehand for a test user, or retrieve from the server response).

For doing that, you need to query all the title elements of the posts and obtain a given property from them (as it could be their innerHTML, value, id...). After that, you have to convert that information to a serializable value (the evaluate function can only return serializable values or it will return null, that is, always return arrays, strings or booleans, for instance, not HTMLElements...).

An example performing that testing would be:

    const likedPosts = ["post1","post2","post3"];

    const list = await page.evaluate(() => {
      let out = []
      /*
        We get all the titles and get their innerHTML. We could also query 
        some property e.g title.getAttribute('value')
      */
      const titles = document.querySelectorAll("#post-title");
      for(let title of titles){
        out.push(title.innerHTML)
      }
      return out;
    });

    expect(list).toEqual(likedPosts);

Those are the most basic cases (and the ones you will be using most of the time) for testing the data of your application.

-Asserting that the `waitFor` is succesful

Another thing you can do instead of evaluate() is, in case you just want to assert a boolean selector or a particular DOM change, is just assign the waitFor() call to a variable and check if it is true. The downside of that method is that you will have to set an estimated timeout to the function that is less than the Jest timeout set at the start. ⏳

If that timeout is exceeded the test will fail. It requires you to put an estimate timeout that you think is enough for the element to be rendered on your page after the request is made (Hmm yeah, I think that around 3 seconds should be enough... 🤔).

For example, we want to check if a new tag has been added to a post querying the number of tag elements present before and after adding tags, that is, comparing their length and see if it has increased, denoting that the tag has indeed been added.

const previousLength = await page.evaluate(() => document.querySelectorAll('#tag').length);

//Add tag async operation...

//Wait maximum 5 seconds to see if the tag has been added.
const hasBeenAdded =  await page.waitForFunction(previousLength => {
       return document.querySelector('#tag')length > previousLength 
      }, {timeout: 5000}, previousLength);

expect(hasChanged).toBeTruthy();

Note that you also have to bind the variables to the waitForFunction() as the third element if you specify the waitForFunction parameter as a closure.

In order to get the data to compare with the information we have retrieved from the page, i.e our ground truth, an approach is to have a controlled test user in which we know what to expect for each one of the tests (number of liked posts, written posts). In this approach we can then hardcode 😱 the data to expect, such as the post titles, number of likes, etc... like we did on the examples of the previous section

You can also fake the response data from the server. That way you can test that the data obtained from the back-end is consistent with what is rendered into the application by responding predictable, inmutable data which you know beforehand. This serves for testing if the application responds predictably (parses correctly) the data returned from the server for a given call.

On the next section we will see how to hijack the requests and provide custom data which you know. Puppeteer provides a method to achieve that, but if you want to dwelve more into faking XMLHttpRequest and pretty much all the data your test manages, you should take a look into Sinon.js 💖

sinonjs / sinon

Test spies, stubs and mocks for JavaScript.

Sinon.JS

Standalone and test framework agnostic JavaScript test spies, stubs and mocks (pronounced "sigh-non", named after Sinon, the warrior)

Compatibility

For details on compatibility and browser support, please see COMPATIBILITY.md

Installation

via npm

$ npm install sinon

or via Sinon's browser builds available for download on the homepage. There are also npm based CDNs one can use.

Usage

See the sinon project homepage for documentation on usage.

If you have questions that are not covered by the documentation, you can check out the sinon tag on Stack Overflow.

Goals

No global pollution
Easy to use
Require minimal “integration”
Easy to embed seamlessly with any testing framework
Easily fake any interface
Ship with ready-to-use fakes for XMLHttpRequest, timers and more

Contribute?

See CONTRIBUTING.md for details on how you can contribute to Sinon.JS

Backers

Thank you to all our backers! 🙏 [Become a backer]

Preact + Typescript + Parcel + Redux Zero: Rebuilding the QMENTA Front-End focusing on Performance and Minimalism.

Albert Alises — Mon, 17 Sep 2018 12:17:01 +0000

At QMENTA we have been rebuilding the front-end from scratch, seeking simplicity and performance not only in design, but also in the technology stack used for it . This article provides a comprehensive overview of the different parts that compound the new platform, such as how decorators are extensively used or the choice of technology stack.

This post was originally posted on Medium

The QMENTA platform has been going on for quite some time now. The old platform front-end was built using well established technologies like JQuery, Dojo or D3. While being feature rich, one of the problems was the scalability and maintainability of such a big codebase and it being quite complex in terms of UX/UI. In medical imaging storing platforms, data and operations are complex enough for the user to manage, so making it more difficult in terms of user experience or visual design is a no-go zone. 🙅🏻

One of the main challenges coming into this year was to rebuild the front-end from scratch to accommodate the new necessities of a growing neuroimaging processing hub, to make it clean and in a way that can be easily maintainable, scalable and up to date with the latest technologies on front-end development.

Figure 1: Register Page for the new front-end

Figure 2: Project List view for all our projects on the new front-end

Having speed, performance and minimalism as a flagship, the aim was to build a single page web application using the FrameworkOfChoice, which can be VueJS, AngularJS, React, or other frameworks such as Hyperapp.

jorgebucaran / hyperapp

1kB-ish JavaScript framework for building hypertext applications

Hyperapp

The tiny framework for building hypertext applications.

Do more with less—We have minimized the concepts you need to learn to get stuff done. Views, actions, effects, and subscriptions are all pretty easy to get to grips with and work together seamlessly.
Write what, not how—With a declarative API that's easy to read and fun to write, Hyperapp is the best way to build purely functional, feature-rich, browser-based apps using idiomatic JavaScript.
Smaller than a favicon—1 kB, give or take. Hyperapp is an ultra-lightweight Virtual DOM, highly-optimized diff algorithm, and state management library obsessed with minimalism.

Here's the first example to get you started. Try it here—no build step required!

<script type="module">
  import { h, text, app } from "https://unpkg.com/hyperapp"
  const AddTodo = (state) => ({
    ...state,
    value: "",
    todos:

…

View on GitHub

Up until there, pretty standard and mainstream definition for a web application project. After pondering the different frameworks and technologies, we chose Preact coupled with Typescript as the core libraries of choice for the project.

Figure 3: Preact and Typescript logos.

But… why Preact + Typescript? 🤔

Preact, according to its official documentation, is a “fast 3kB alternative to React with the same modern API”. It offers everything we like and love about React such as the Virtual DOM, Component-Based development, lifecycle hooks and jsx syntax for generating dynamically, data-driven interfaces.

Preact does all this while keeping the API leaner (React 16.2.0 + React DOM is 31.8Kb while Preact is only 4Kb, both gzipped), making it faster, more lightweight, and reducing a lot of the noise added by React. The principal differences with React can be seen here. Some of them are:

this.props and this.state are passed to render() for you.
You can just use class for CSS classes.
Getting rid of a lot of React / React DOM specific functions like React.CreateElement or ReactDOM.render , being separate exports thus avoiding the aliasing, making your code cleaner and more readable.

Regarding performance, testing it on a simple TODO application, the results are astounding, with Preact being among the fastest of them approached by Vue.js and circa 170ms faster than React. Amazing, isn’t it? 🌠

Figure 4: TodoMVC Performance comparison between different frameworks. Seen at: https://developit.github.io/preact-perf/

You can perform the performance test on your device by going here.

Not everything is great of course, one can find that the community is not as big or responsive as the React one (it is not that widely used after all). Some sweet functionalities are still not there, such as support for fragments (So you still have to create some good old div wrappers). Furthermore, some libraries are still not supported, but worry not, preact-compat creates a layer on top of Preact to make it fully compatible with React. Magic!⚡️

preactjs / preact-compat

ATTENTION: The React compatibility layer for Preact has moved to the main preact repo.

ATTENTION: preact-compat has moved to the main repo.

The code here is only meant for the older Preact 8.x release line. If you're still on Preact 8.x we highly recommend upgrading to the 10.x release line as it includes significant improvements and a much more stable React compatibility layer.

🚨 Note: This module is for Preact 8.x and prior - Preact X includes compat by default For Preact X, please uninstall preact-compat and replace your aliases with preact/compat.

This module is a compatibility layer that makes React-based modules work with Preact, without any code changes.

It provides the same exports as react and react-dom, meaning you can use your build tool of choice to drop it in where React is being depended on.

Interested? Here's an example project that uses preact-compat to work with an existing React library unmodified achieving more than 95% reduction in size:

…

View on GitHub

Figure 5: Analysis List View

We ❤️ Typescript. A lot. For an application that is rich in data and manages a lot of different metadata and results from APIs, Typescript offers us static type checking that comes very handy when defining the different data structures that our application handles, as well as the structure of the props and state of the different components, so we know what to expect, have it documented and have all the data to be consistent at all different stages.

You can create interfaces with Typescript that characterize the input/output data your application manages. In our case, it helps modeling the data necessary to characterize a subject, or an analysis so everything is consistant and we know what to expect when dealing with those structures.

export interface AnalysisInput {
  container_id: number,
  date: { $date: number },
  in_out: string,
  filters?: any[][],
  passed: boolean,
  ssid: string,
  subject_name: string
}

export interface AnalysisSettings {
  acpc_alignment: string,
  age_months: number,
  alignment_tool: string,
  input: AnalysisInput
}

With Typescript, you can also create Custom Components like the one below. This enforces the classes extending ComponentForm to implement methods for handling the form change and also setting the form model (i.e the object with all the fields required for the form such as the user, password, etc…), this model is then required as the state of the component, also a method submitForm() has to be implemented. With that, we have a skeleton or structure that all forms follow with a generic form component that can have any given number of fields.

import { h, Component } from "preact";

interface FormManagement<M> {
  form: M,
  message: string
}

export abstract class ComponentForm<props, model> extends Component<props, FormManagement<model>> {

  protected setFormModel (model: any) {
    this.setState({ form: new model })
  }

  protected handleFormChange(change) {
    this.setState(({ form, ...state }) => ({
      form: { ...form, ...change },
      ...state
    }));
  }

  abstract submitForm(...args): void;
}

An example of a simplified generic Preact Component our application uses that enforce Typescript. We can see the different lifecycle hooks and how the props and state of the component are set as Typescript interfaces.

mport { h, Component } from "preact";

export interface CommonSelectorAttrs {
  options: any[];
  class?: string;
  value?: any;
  printBy?: string;
  onChange?: (any) => void;
}

export interface CommonSelectorState {
  visible: boolean;
  innerValue: string;
}

export default class CommonSelector extends Component<CommonSelectorAttrs, CommonSelectorState> {

  state = { 
    visible: false, 
    innerValue: ""
  };

  getValue = (entry) => String(this.props.printBy ? entry[this.props.printBy] : entry);

  componentDidMount(): void {
    this.props.value && this.setState(() => ({ innerValue: this.getValue(this.props.value) }));
  }

  selectOption(opt: any): void {
    this.props.onChange.call(null, { target: { value: opt }});
  }

  closeTooltip(): void {
    this.setState(() => ({ visible: false }));
    this.checkMatch();
  }

  getMatcher(opt: any): boolean {
    return this.getValue(opt) === this.state.innerValue;
  }

  checkMatch(): void {
    const match = this.props.options.find((opt) => this.getMatcher(opt));
    !!match ? this.selectOption(match) : this.setState(() => ({ innerValue: "" }));
  }

  explicitSelection(opt: any): void {
    const val = this.getValue(opt);
    this.setState(() => ({ innerValue: val }));
    this.closeTooltip();
  }

  setValue(){
    if(this.state.innerValue === 'undefined'){
      return "";
    }else{
      return this.state.innerValue;
    }
  }

  render() {
    return (
      <div>
        <div>
          <p>
            <input placeholder="Select one option" />
          </p>
        </div>
        <div>
          {this.props.options
            .map((opt) => (
              <div onClick={() => this.explicitSelection(opt)}>
                <span>{this.getValue(opt)}</span>
              </div>
          ))}
        </div>
      </div>
    )
  }
}

Decorators, Decorators… 💎

Ah, Javascript decorators. As a concept, they simply act as wrappers to another function, extending its functionality, like higher-order functions. We extensively use decorators to keep our code cleaner and separate the back-end, state or application management concerns and provide a more structured way to define common functions across components like connecting to the Redux store, connecting to the API or defining some asynchronous behavior to happen before or after the responses are sent (sort of like method proxies), so we do not have to repeat code and provide an elegant, minimal way to define these behaviors. We use them for:

- Asynchronous Method Interceptors

For managing asynchronous behavior we use kaop-TS , which is a decorator library that provides some method interceptors written in Typescript. With them, we can plug in behavior at a join point on the asynchronous method, like perform some operations before the method starts, or after the method has finished, or plugging in a method that intercepts an error and performs some logic. We can see the beforeMethod decorator being used in the snippet below where we define the http decorator.

k1r0s / kaop-ts

Simple Yet Powerful Library of ES2016 Decorators with Strongly typed method Interceptors like BeforeMethod, AfterMethod, OnException, etc

Lightweight, solid, framework agnostic and easy to use library written in TypeScript to deal with Cross Cutting Concerns and improve modularity in your code.

Short Description (or what is an Advice)

This library provides a straightforward manner to implement Advices in your app. Advices are pieces of code that can be plugged in several places within OOP paradigm like 'beforeMethod', 'afterInstance'.. etc. Advices are used to change, extend, modify the behavior of methods and constructors non-invasively.

For in deep information about this technique check the resources.

Demo

https://jsbin.com/bogecojuvi/edit?js,console

Get started

npm install kaop-ts --save

Use a join point to plug it to any method/class:

import { afterMethod } from 'kaop-ts'
const double = afterMethod(meta => meta.result *= 2)

class DummyExample {

  @double
  static calculateSomething (num, num2) {
    return num * num2
  }
}

DummyExample.calculateSomething(3, 3

…

View on GitHub

- Connecting with and Managing API calls

For managing the calls to the QMENTA API, we implemented a @platformRequest(url,method) decorator that you can wrap in any function of with signature function(params,error?,result?) and convert it into an asyncronous call to the API with certain parameters to send in the request and receive the result JSON object from the call or the error thrown by the request. The implementation of the decorator can be seen below as well as an example method calling it.

const http = options => meta => {
  if(!options.method) options.method = "get";
  const [ params, ...aditional ] = meta.args;
  options[options.method === 'get' ? 'params' : 'data'] = params;
  (request as any)({ ...options })
  .then(res => {
    const data = res.data;
    meta.args = [params, ...aditional, null, res.data];
    meta.commit();
  })
  .catch(err => {
    meta.args = [params, ...aditional, err, null];
    meta.commit();
  })
};

const checkError = meta => {
  const [err, result] = meta.args.slice(-2);
  checkInvalidCredentials(err);
  if(err) return;
  if(typeof result !== "object") {
    meta.args.splice(-2);
    meta.args = [ ...meta.args, new Error("Wrong response format! (not a json obj)"), null ];
  }
}

const stringifyParams = meta => {
  const [ params, ...args ] = meta.args;
  meta.args = [ stringify(params), ...args ];
}

export const platformRequest = (url, method = "get", noop = _ => _) => beforeMethod(
  method === "get" ? noop : stringifyParams,
  http({ method, url }),
  checkError)

/* USAGE EXAMPLE */
interface ChangePasswordRequest {
  old_password: string,
  new_password: string,
  new_password_confirm: string
}

@platformRequest("/change_password", "post")
  RecoverPassword(params : ChangePasswordRequest, err?, result?) {
    if(err) {
      throw err;
      //Cannot change the password
    } else {
      //Password changed succesfully!
    }
 }

The decorator uses axios under the hood to perform the request 🕵.

An implementation of it (as a minimal library) wrapping the Fetch API can be seen on the http-fetch-decorator repo:

aalises / http-fetch-decorator

Simple Fetch interface http decorator wrapper for your functions.

HTTP Fetch Decorator

Simple Fetch interface decorator wrapper for your functions.

$ npm install http-fetch-decorator

Signature

Then you can place the decorator which has the same input structure as the fetch function. The parameters of the request or the data to send as a body are passed via arguments to the wrapped function, and the result and error objects are available as parameters of the function as well:

@Fetch(Url: String, initObj?: Object)
static wrappedFunction(params: Object, result? : Response, err? : any){
  ...
}

How to use it

import Fetch from "http-fetch-decorator"
class AnyES6Class {
  @Fetch("apiexample/getsomething", {method: 'GET',mode:'cors'})
  static parseResponse({id: '1'},result,err) {
    if(err) throw err;
    //Result contains the

…

View on GitHub

Also, the state management and routing of our application use decorators to extend functionality to the components to, for example, connect it to the store or listen to be rendered at a specific route. On the next section we will talk a little bit more about it.

Figure 6: Specific Subject files viewing with the edit file metadata modal.

State Management and Routing 🚀

State management is one of the main concerns of any growing React application. When the number of entities and components keep growing, the need for global state management arises. Redux is one of the mainstream solutions that aims to solve that. This post assumes some previous knowledge of how Redux operates; if not, here you can find a guide on how it works .

In our application, we did not want to have a big store and we tried to keep it as small as possible, reducing the use of the shared state, enforcing encapsulation and separation of concerns. Given so, we decided to use a lightweight (less than 1Kb) version called Redux-Zero. While having some differences, it also reduces a lot of the unnecessary overhead (for the purpose of our application) that Redux has. It still has a store (albeit just one), which provides all the global state that we want to manage; in our case, session and project information, current pages, notifications of the current project id, among others. It also has no reducers, which ironically does reduce the complexity of the library quite a lot.

redux-zero / redux-zero

A lightweight state container based on Redux

Read the intro blog post

Installation

To install the stable version:

npm i redux-zero

This assumes that you’re using npm with a module bundler like webpack

How

ES2015+:

import createStore from "redux-zero";
import { Provider, connect } from "redux-zero/react";

TypeScript:

import * as createStore from "redux-zero";
import { Provider, connect } from "redux-zero/react";

CommonJS:

const createStore = require("redux-zero");
const { Provider, connect } = require("redux-zero/react");

UMD:

<!-- the store -->
<script src="https://unpkg.com/redux-zero/dist/redux-zero.min.js"></script>
<!-- for react -->
<script src="https://unpkg.com/redux-zero/react/index.min.js"></script>

<!-- for preact -->
<script src="https://unpkg.com/redux-zero/preact/index.min.js"></script>

<!-- for vue -->
<script

…

View on GitHub

Figure 7: Brain Tractography Fiber visualization on the front-end using WebGL

To get it up and working, just wrap your root component with the <Provider store={store}/> component and set the store on it, an object created by the createStore(state) method, where the state is the object that contains our shared state. To change that state, you create actions which are just pure functions that update this global state , e.g setSession = (state,val) => ({sessions: val});

To call those actions from a component, we have to connect that component to the store. Connecting a given component to the store allows the component to gain access to some actions and the global state via props. We created a decorator to simplify the process of connecting a component to the store.

import { h, Component } from "preact";
import { Connect } from "redux-zero/preact";

export default function(actions = {}): any {
  return Child => props => (
    <Connect mapToProps={state => ({ ...state })} actions={actions}>
      {mappedProps => <Child {...mappedProps} {...props} />}
    </Connect>
  )
}

With this decorator, we can plug it in on top of any component specifying the actions the component will get as props. e.g by putting @connectStore({removeSession, setCurrentPages}); right on top of the declaration of the component, you have access to these actions inside the component which update the global state on the store, while also having access to the global state itself via props ( this.props.removeSession(); ). With this method, we provide a cleaner, more elegant and compact way to connect a component to the store.

Another integral part of any modern application is the option to route between the different views of the project depending on the URL or other parameters, being able to pass parameters to the routes, etc. A common solution is to use the amazing router that comes with React . As much as we like it, it comes with a lot of functionality that we would not really be using, so we made our own preact-routlet , a simple router for Preact/React based in decorators.

k1r0s / preact-routlet

Simple `Component Driven` Routing for Preact/React using ES7 Decorators

Preact Routlet

This package contains routing functionalities for Preact and, now from 1.0.0 React applications as well. Instead of using HTML5 history API it uses the oldie /#/what-ever hash routing (this will change in the future).

This project was created by exploring contextual ways to define routes rather than placing all the routes in a single file.

Usage:

Available imports:

// if you're using React
import { renderOnRoute, navigate, RouterOutlet, PathLookup, routePool, Link } from "preact-routlet/react"
// if you're using Preact
import { renderOnRoute, navigate, RouterOutlet, PathLookup, routePool, Link } from "preact-routlet/preact"

Either from "preact-routlet/preact" or from "preact-routlet/react"

Place your RouterOutlet element somewhere in your JSX:

<div>
  <RouterOutlet />
</div>

Plug the renderOnRoute decorator on some component

@renderOnRoute("/login")
export default class Login extends Component<any, any> {

…

View on GitHub

The intricacies of it are simple, just wrap your application with the router component <RouterOutlet /> and you are ready to go. You can also wrap some components with <PathLookup shouldRender={condition}/> specifying a condition to render some path, or use the <RouterOutlet redirect="/route" shouldRedirect={condition} /> to specify a condition which, in case it is met, the router automatically redirects to the specified route (for example, we use it to redirect to the login if the session is invalid or has expired).

To navigate to a route you just have to call navigate("/route") and to specify a Component to be rendered at a specific route, you just have to plug the decorator on top of the component e.g @renderOnRoute("forgot-password") making it clear and visual in which route the component is rendered.

With that, we have a compact way of representing routing and state management with the signatures on top of the component that makes it very readable. A dummy component that connects to the store and is rendered on a given route can be seen below.

import { h, Component } from "preact";
import { renderOnRoute, navigate } from "preact-routlet";
import { setLoginMessage } from "../actions";
import connectStore from "../../../connect";
import { platformRequest } from "../../../services/api-decorators";

//With these decorators, we know the route this component is rendered at and which actions does it have access to, in a compact way
@renderOnRoute("/forgot-password") @connectStore({ setLoginMessage })
export default class ForgotPassword extends Component<any, any> {

  //Call the forgot_password API with a POST
  @platformRequest("/forgot_password", "post")
  performLogin(params, err?, result?) { //Params are the parameters of the request e.g {email: "test@gmail.com , user_id: 1234}
    if(err || result.error) {
      this.setState({ message: "There was an error with the request" })
    } else {
      this.props.setLoginMessage(result.message); //Calling the store to set a login warning message
      navigate("/login"); //Navigate back to the login using the router
    }
  }

   render() {
     return (
        <div>
          Just an example component with some decorators...
        </div>
   }
}

Bundling with Parcel 📦

Parcel, not to be confused with the australian band Parcels, defines itself as a “blazing fast, zero configuration web application bundler”. At the start of the project, we used the fairly standard Webpack for bundling our application. It required quite a lot of plugins and configuration. (webpack.config.ts). Switching to Parcel, we don’t need configuration for typescript or html files anymore, just adding npm install --save-dev parcel-bundler parcel-plugin-typescript does the trick.

The only remaining thing is to specify an entry point and output directory and voilà, it just works. The difference in speed and performance compared to webpack is not very acute in our case (it’s essentially the same in terms of speed), but it’s the zero configuration and minimality of Parcel what makes it our bundler of choice for the project.

parcel-bundler / parcel

The zero configuration build tool for the web. 📦🚀

Parcel is a zero configuration build tool for the web. It combines a great out-of-the-box development experience with a scalable architecture that can take your project from just getting started to massive production application.

Features

😍 Zero config – Parcel supports many languages and file types out of the box, from web technologies like HTML, CSS, and JavaScript, to assets like images, fonts, videos, and more. It has a built-in dev server with hot reloading, beautiful error diagnostics, and much more. No configuration needed!
⚡️ Lightning fast – Parcel's JavaScript compiler is written in Rust for native performance. Your code is built in parallel using worker threads, utilizing all of the cores on your machine. Everything is cached, so you never build the same code twice. It's like using watch mode, but even when you restart Parcel!
🚀 Automatic production optimization – Parcel optimizes your whole app for production automatically…

View on GitHub

Figure 8: Screenshot of the build of the whole application. Parcel’s magic💥

The only downside is that, in order to get the hot reloading working for the dev server in Preact + Typescript, you have to add the module.hot.accept() flag to your root component and specify some types in the render function (the third argument as foo.lastChild as Element for Typescript not to complain. The fix can be seen on the following snippet.

import { h, render } from "preact";
import Main from "./components/main"

declare const module: any

const mountNode = document.getElementById('root');

render(<Main />, mountNode, mountNode.lastChild as Element);

// Hot Module Replacement
if (module.hot) {
    module.hot.accept();
}

Unit and e2e acceptance testing with Jest + Puppeteer

Testing is an integral part of any project. In our project, we use the fairly standard Jest for testing our components coupled with Puppeteer , wich is a web scraper, or having your own highly trained monkey perform the operations you tell him/her on the browser, like clicking a certain button or dragging the mouse over an element. Using those, we can perform some operations on the front-end via a headless Chrome API and then check for expected results with Jest, like checking an element of confirmation appears or the warning message displayed is correct👌. If you want to learn more on how to use Jest + Puppeteer for testing in React, there is a nice article talking about it.

puppeteer / puppeteer

JavaScript API for Chrome and Firefox

Puppeteer

Puppeteer is a JavaScript library which provides a high-level API to control Chrome or Firefox over the DevTools Protocol or WebDriver BiDi Puppeteer runs in the headless (no visible UI) by default

Get started | API | FAQ | Contributing | Troubleshooting

Installation

npm i puppeteer # Downloads compatible Chrome during installation.
npm i puppeteer-core # Alternatively, install as a library, without downloading Chrome.

Example

import puppeteer from 'puppeteer';
// Or import puppeteer from 'puppeteer-core';
// Launch the browser and open a new blank page
const browser = await puppeteer.launch();
const page = await browser.newPage();

// Navigate the page to a URL.
await page.goto('https://developer.chrome.com/');

// Set screen size.
await page.setViewport({width: 1080, height: 1024});

// Type into search box using accessible

…

View on GitHub

Just an example of testing the pagination component using Jest.

import { h, render } from 'preact';
import Pagination, {generateMidPageTabValues} from '../../src/components/pagination-component';

const spy = jest.fn()

describe("<Pagination /> e2e tests", () => {

  let scratch = null;
  let component = null;

  beforeEach(done => {
    scratch = document.createElement('div');
    render(<Pagination initialPage={1} ref={ref => component = ref} pageChange={(from, to) => spy(from, to)} totalItems={45}/>, scratch);
    done()
  });

  it("should display proper information about pages", () => {
    expect(scratch.innerHTML).toContain("Showing items 1 to 15 of 45");
  });
  it("shouldn't allow to decrease current page if we're on the first page", () => {
    expect(component.state.prevAllowed).toBe(false);
  });
  it("should properly increase current page", (done) => {
    component.pageForward();
    setTimeout(_ => {
      expect(scratch.innerHTML).toContain("Showing items 16 to 30 of 45");
      expect(spy).toHaveBeenLastCalledWith(15, 30);
      done();
    }, 1000);
  });
  it("Should correctly compute first page indices", () => {
    expect(generateMidPageTabValues(1,5,10)).toEqual([2,3,4,5,6]);
    expect(generateMidPageTabValues(4,5,10)).toEqual([2,3,4,5,6]);
  });
  it("Should correctly compute last page indices", () => {
    expect(generateMidPageTabValues(13,5,15)).toEqual([10,11,12,13,14]);
    expect(generateMidPageTabValues(11,5,15)).toEqual([10,11,12,13,14]);
  });
  it("Should correctly compute middle pages indices", () => {
    expect(generateMidPageTabValues(10,5,15)).toEqual([8,9,10,11,12]);
    expect(generateMidPageTabValues(7,5,15)).toEqual([5,6,7,8,9]);
  });
  it("Should correctly compute indices when few pages", () => {
    expect(generateMidPageTabValues(1,5,5)).toEqual([2,3,4]);
    expect(generateMidPageTabValues(2,5,3)).toEqual([2]);
    expect(generateMidPageTabValues(2,5,2)).toEqual([]);
    expect(generateMidPageTabValues(1,5,1)).toEqual([]);
  });
});

The building, testing and deploying process is automated using Jenkins , with the tests running in a docker container in order to perform the tests in an environment with all the graphical libraries puppeteer requires. The fairly simple pipeline can be seen in Figure 9:

Figure 9: Jenkins pipeline for deploying the front-end

We build the binaries, perform the unit tests and then deploy to a testing dominion which varies based on the git branch we are on. Then we perform the e2e tests on that dominion.

The docker image used for the container in which Jenkins runs the pipeline is a custom version of the Puppeteer Docker Image , based on the ubuntu 16.04 image with node 8. The dockerfile can be seen below:

We add the “deployuser” to the container because Jenkins mounts its workspace directory (owned by deployuser) and it requires the user inside the container and outside to be the same in order to perform all the operations required for the deployment to be succesful.

This way, we avoid the whole application to suddenly crash and burn or turn into one of those amazing 90’s websites.

Summary

In this article we have presented an overview of the technology stack we used for rebuilding the QMENTA front-end and how it focuses on being small, efficient and simple. We have also seen how we use decorators in our project and the different parts that compound it such as API calls, routing, state management etc.

By setting the foundations and patterns of the project, the next steps are continuously improving the new front-end in a scalable and maintainable way and adding meaningful features to match the functionality of the old platform, while keeping it minimal. You can see how it goes here. 👋

Special kudos 🙌 to

Ciro IvanFollow

/k1r0s

for setting the foundations of the project, carrying the heavyweight through most of it and teaching me the ways of the H̶a̶c̶k̶e̶r̶m̶a̶n̶ Javascript ninja. 🤖 🏋🏻

Want to experiment with these technologies in your next projects? Yay! Here you have some boilerplates we created in github to get you up and running as soon as possible.🤘🏼

Preact + Typescript + Parcel

aalises / preact-typescript-parcel-starter

Starter with Preact - Typescript - Parcel Bundler

Preact + Typescript + Parcel Starter

Zero configuration bundling and lightweight state management and view => Preact + Typescript + Parcel Bundler + Redux Zero + Jest + Pupetteer

This starter project contains many features and technologies to start the development ASAP.

Features:

TypeScript: Strong typing and the future of JavaScript
Preact: dom manipulation + components
Redux-Zero: state management
Preact-Bind-Group: Group Form fields onChange Events to a single Callback, making forms easier to manage
Parcel: 0 configuration bundler
Jest: Delightful javascript testing
Puppeteer: Headless chrome node API scrapper
Lynt: 0 configuration linting for TS + React

run development server `npm run dev`

build the project (on /dist) `npm run build`

run tests `npm run test`

run linting `npm run lint`

The starter includes a basic sample application showcasing the different technologies using Bulma for styles. The example consists on a restaurant order making form with validation/model and some global state…

View on GitHub

Preact + Poi

k1r0s / preact-poi-starter

Preact Example App powered by Poi and BabelJS

Preact Poi starter

So whats the deal here?

Poi justs works. Of course Poi will try to look up a .babelrc. Since Preact has a different jsx pragma you must have transform-react-jsx plugin with { pragma: "h" } opt at least to work with.

{
  "sourceMaps": true,
  "presets": [
    ["es2015", { "loose":true }],
    "stage-0"
  ],
  "plugins": [
    ["transform-decorators-legacy"],
    ["transform-react-jsx", { "pragma": "h" }]
  ]
}

For this example I added transform-decorators-legacy as well.

run development server

npm run dev aka $ poi [root file]

run production build

npm run build aka $ poi build [root file]

View on GitHub

Preact + Typescript + Webpack

k1r0s / bleeding-preact-starter

TypeScript · Preact · Redux-zero => frontend starter with bleeding features. Check it out!

Bleeding Frontend Starter

Preact + TypeScript + Redux-Zero + Moar..

This starter project contains many features to speedup development and have fun which is pretty handy today.

Features:

TypeScript Strong typing and the future of JavaScript
Preact dom manipulation + components
Redux-Zero state management
Preact-Routlet Simple Component drive Routing
Http-Decorator Wrap your components with axios, no more async management
Preact-Stylesheet-Decorator Wrap your components with scoped css
Preact-Bind-Group Group Form fields onChange Events to a single Callback

common folder contains Connect decorator for redux-zero (which is not yet included on the lib)

Heading production env -> Polyfills, Shims & Extensions

I recommend to install core-js and import all its contents on your main file import 'core-js'

View on GitHub

Forem: Albert Alises

Create an Interactive Bash Command for searching and checking out Git Branches on the Terminal using fzf

Introducing Fzf

junegunn / fzf

🌸 A command-line fuzzy finder

Highlights

Sponsors ❤️

sharkdp / bat

A cat(1) clone with wings.

Sponsors

Syntax highlighting

Git integration

Show non-printable characters

Creating the interactive branch navigator with Fzf

Dealing with Asynchrony when Writing End-To-End Tests with Puppeteer + Jest

jestjs / jest

Delightful JavaScript Testing.

🃏 Delightful JavaScript Testing

Table of Contents

Getting Started

puppeteer / puppeteer

JavaScript API for Chrome and Firefox

Puppeteer

Get started | API | FAQ | Contributing | Troubleshooting

Installation

Example

🤘 But hey, here you have a great tutorial on how to test with Puppeteer + Jest, to get you started.

Waiting, Waiting, Waiting...⏰

Retrieving data from selectors after an Async operation

- Checking that a DOM element has appeared

- Checking for matching property values (e.g innerHTML, option...)

-Asserting that the waitFor is succesful

sinonjs / sinon

Test spies, stubs and mocks for JavaScript.

Sinon.JS

Compatibility

Installation

Usage

Goals

Contribute?

Backers

Sponsors

Intercepting Requests and faking Requests with Puppeteer

Disclaimer: For the API we assume the somewhat typical format https://api.com/v1/endpoint_name, so the parsing to retrieve the endpoint is specific to that format for exemplification purposes, you can detect the Request made based on other parameters of course, your choice 💪

Getting the data to assert from the Response

✍🏼 Note: The page.on() methods for request and response are tipically placed on the beforeAll() method of your tests, after declaring the page variable, as they define a global behavior of your test.

Summary

Got any questions?! Go out here, start implementing tests like a madman and pray for them to pass, happy coding! 🙇🏻

Preact + Typescript + Parcel + Redux Zero: Rebuilding the QMENTA Front-End focusing on Performance and Minimalism.

jorgebucaran / hyperapp

1kB-ish JavaScript framework for building hypertext applications

Hyperapp

But… why Preact + Typescript? 🤔

preactjs / preact-compat

ATTENTION: The React compatibility layer for Preact has moved to the main preact repo.

ATTENTION: preact-compat has moved to the main repo.

Decorators, Decorators… 💎

- Asynchronous Method Interceptors

k1r0s / kaop-ts

Simple Yet Powerful Library of ES2016 Decorators with Strongly typed method Interceptors like BeforeMethod, AfterMethod, OnException, etc

Short Description (or what is an Advice)

Demo

Get started

- Connecting with and Managing API calls

aalises / http-fetch-decorator

Simple Fetch interface http decorator wrapper for your functions.

HTTP Fetch Decorator

Signature

How to use it

State Management and Routing 🚀

redux-zero / redux-zero

A lightweight state container based on Redux

Table of Contents

Installation

How

k1r0s / preact-routlet

Simple `Component Driven` Routing for Preact/React using ES7 Decorators

Preact Routlet

Usage:

Bundling with Parcel 📦

-Asserting that the `waitFor` is succesful

Disclaimer: For the API we assume the somewhat typical format `https://api.com/v1/endpoint_name`, so the parsing to retrieve the endpoint is specific to that format for exemplification purposes, you can detect the Request made based on other parameters of course, your choice 💪

Getting the data to assert from the `Response`

✍🏼 Note: The `page.on()` methods for request and response are tipically placed on the `beforeAll()` method of your tests, after declaring the page variable, as they define a global behavior of your test.

run development server `npm run dev`

build the project (on /dist) `npm run build`

run tests `npm run test`

run linting `npm run lint`