DEV Community: Dor Shinar

Avoiding impossible state with TypeScript

Dor Shinar — Wed, 21 Oct 2020 16:25:55 +0000

I love TypeScript. I’ve been using it for over 2 years in various projects, and the more I use it the less compelling I find vanilla Javascript.

Not that there is anything wrong with vanilla Javascript (my blog is vanilla!), but I think that when it comes to medium to large projects, Typescript makes a lot of things easier.

Among the many good things Typescript offers, I’d like to address one that, in my experience, has saved me quite a few bugs.

Let’s start with an example first.

The code will contain React components, but the general principle stays the same with other frameworks as well.

Let’s say we have a very rudimentary loading indicator in our app:

import React from "react";

type RequestStatus = "PENDING" | "SUCCESSFUL" | "FAILED";

interface RequestLoadingIndicatorProps {
  state: RequestStatus;
}

const styles: Record<RequestStatus, React.CSSProperties> = {
  PENDING: {
    backgroundColor: "blue",
    borderRadius: "50%",
    width: "50px",
    height: "50px",
  },
  FAILED: {
    backgroundColor: "red",
    borderRadius: "50%",
    width: "50px",
    height: "50px",
  },
  SUCCESSFUL: {
    backgroundColor: "green",
    borderRadius: "50%",
    width: "50px",
    height: "50px",
  },
};

export const RequestLoadingIndicator: React.FC<RequestLoadingIndicatorProps> = ({
  state,
}) => {
  return <div style={styles[state]} />;
};

You can see what it look like here. It’s nothing special, but our users are content.

In order to display a loading indicator in our system all we need is to tell it in what state our request is, and it will display a circle in the corresponding color.

One day, we choose to allow adding a message to go along with FAILED requests. We can modify our props interface like so:

interface RequestLoadingIndicatorProps {
  state: RequestStatus;
  message: string;
}

And our component will now display the message:

export const RequestLoadingIndicator: React.FC<RequestLoadingIndicatorProps> = ({
  state,
  message,
}) => {
  return <div style={styles[state]}>{message}</div>;
};

A while passes and everything is just fine, but then - an engineer on our team is refactoring some old code, and rewrites some code to fetch data from your server.

When the data arrives, the engineer renders a SUCCESSFUL loading indicator with a message, although our guidelines specifically say that successful indicator should not have a message.

function GetData() {
  const { data } = useData();

  if (data) {
    return (
      <RequestLoadingIndicator state="SUCCESSFUL" message="data fetched" />
    );
  }
}

Impossible State

What we have here is an impossible state!

An impossible state is a certain combination of fields and values, that should never co-exist simultaneously.

In other words - an “impossible state” might be a possible state in that if we disregard our company guidelines/lint rules/compiler, the state may occur, but we should never accept it, and therefore must make sure it never occurs (whether intentionally or unintentionally).

You don’t need Typescript to avoid impossible states. In fact - you could get away without anything stopping you from making the impossible state mistake, given that everyone in your team is aware of it, and all of you are responsible engineers with buckets of ownership.

That might be the case today. What will happen when your company doubles in size? or triples? or quadruples?

Would you still feel like word-of-mouth is good enough?

I strongly disbelieve that. Not because I don’t trust other engineers around me, I have complete faith in them. I like to think about it in exponential terms - if your team doubled in size, you’d need 4 times the efforts to preserve code quality.

To comply with that, we need some mechanism that would prevent, to the highest degree possible, the presence of such “impossible states”.

Naïve solution

One way to go about it, is to document the fact that SUCCESSFUL or PENDING requests should have no message, like so:

interface RequestLoadingIndicatorProps {
  state: RequestStatus;
  // Message should only be present when state is `FAILED`
  message: string;
}

But this method, in my opinion, is error prone - in the end the only way to find it is with a human eye, and humans are prone to failure.

A better way

But I am here to present to you a better way. There is a very simple way in which we can ensure we always have exactly what we want, nothing more and nothing less.

We can leverage Typescript’s powerful Union Types. In essence, union types allow us to make new types that act as an OR clause in a way.

Let’s start with a quick example. Say we have an intelligent logger that can both print single log messages, and can concatenate log messages if passed as an array.

function log(messages) {
  if (Array.isArray(message)) {
    console.log(messages.join(" "));
  }
  if (typeof messages === "string") {
    console.log(messages);
  }

  throw new Error("unsupported type!");
}

log("hello"); // prints 'Hello'.
log(["Hello", "World"]); // prints 'Hello World'.

If we wanted to type it, we could do it naïvely like so:

function log(messages: any) {
  if (Array.isArray(message)) {
    console.log(messages.join(" "));
  }
  if (typeof messages === "string") {
    console.log(messages);
  }

  throw new Error("unsupported type!");
}

log("Hello"); // prints 'Hello'.
log(6); // this function will pass at compile time, but fail in runtime.

But that won’t help us much, leaving us with pretty much untyped javascript. However, using union types we could type the function like this:

function log(messages: string | string[]) {
  if (Array.isArray(message)) {
    console.log(messages.join(" "));
  }
  if (typeof messages === "string") {
    console.log(messages);
  }

  throw new Error("unsupported type!");
}

log("Hello"); // prints 'Hello'.
log(["Hello", "World"]); // prints 'Hello World'
log(6); // Compile time error: Argument of type 'number' is not assignable to parameter of type 'string | string[]'.

Now that we know how to work with union types, we can use them to our advantage in our loading indicator.

One interface to rule them all? No

Instead of using a single interface for all the possible states of the request, we can split them up, each having their own unique fields.

interface PendingLoadingIndicatorProps {
  state: "PENDING";
}

interface SuccessfulLoadingIndicatorProps {
  state: "SUCCESSFUL";
}

interface FailedLoadingIndicatorProps {
  state: "FAILED";
  message: string;
}

type RequestLoadingIndicatorProps = PendingLoadingIndicatorProps | SuccessfulLoadingIndicatorProps | FailedLoadingIndicatorProps;

The highlighted part is where the magic happens. With it we specify all the different types of props we accept, and only allow a message on FAILED requests.

You’ll immediately see that Typescript is yelling at our component:

So we’ll change our component just a little:

export const RequestLoadingIndicator: React.FC<RequestLoadingIndicatorProps> = (
  props
) => {
  if (props.state === "FAILED") {
    return <div style={styles[props.state]}>{props.message}</div>; // no error!
  }

  return <div style={styles[props.state]} />;
};

Inside our if block Typescript is able to narrow down the type of our props from PendingLoadingIndicatorProps | SuccessfulLoadingIndicatorProps | FailedLoadingIndicatorProps to FailedLoadingIndicatorProps, and ensures us that the message prop exists.

If we now tried to render our RequestLoadingIndicator with a message and a state other than FAILED, we would get compile time error:

Embracing difference

We could stop at that and call it a day, or we can take it up a notch.

What if we wanted to change our SUCCESSFUL loading indicator to show an animation, and allow consumers of our indicator to pass a callback that fires when the animation ends?

With a monolithic interface, we’d go through the same trouble as we did when we added the message field.

interface RequestLoadingIndicatorProps {
  state: RequestStatus;
  // Message should only be present when state is `FAILED`
  message: string;
  // onAnimationEnd should only be present when state is `SUCCESSFUL`
  onAnimationEnd?: () => void;
}

See how quickly it gets out of hand?

Our union types make this a non-issue:

interface PendingLoadingIndicatorProps {
  state: "PENDING";
}

interface SuccessfulLoadingIndicatorProps {
  state: "SUCCESSFUL";
  onAnimationEnd?: () => void;
}

interface FailedLoadingIndicatorProps {
  state: "FAILED";
  message: string;
}

type RequestLoadingIndicatorProps =
  | PendingLoadingIndicatorProps
  | SuccessfulLoadingIndicatorProps
  | FailedLoadingIndicatorProps;

Now, we only allow our indicator’s consumers to pass onAnimationEnd when state is SUCCESSFUL, and we have Typescript to enforce that.

Notice that we used ?, so we don’t force anyone to pass empty functions.

Summary

Obviously, this is a contrived example, but I hope it makes it clear how we can leverage Typescript’s union types and type narrowing, ensuring as much type safety as possible, while still leveraging some of Javascript’s dynamic nature.

Thank you for reading!

(cover photo by Matt Atherton on Unsplash)

Creating Custom Github Actions is Easy!

Dor Shinar — Wed, 15 Jul 2020 12:41:02 +0000

I'm a big fan of Github actions. I've started using them right when they came out of beta. Creating workflows is very easy and uses a familiar yml syntax as I've explained in a previous article I've written - Continuous Integration with Github Actions and Puppeteer. I encourage you to give it a read, you might find it useful as well.

My workflow was very simple - install dependencies, lint, build, test. All this happened in parallel to a Vercel deployment which is triggered on new commits. It worked great, but I had an issue which irritated me - I had to build my blog twice on each push - 1 in my CI workflow, against which I ran the tests, and 1 in my Vercel build.

The solution seemed pretty simple - just run the tests against the Vercel build and Voila! all problems solved. However reality proved me wrong, and it was not as simple as I thought it should be. Although GitHub has a Deployments API, and Vercel was reporting deployments correctly, there was no way to access them in my build.

After a lot of research, I've reached a conclusion that I must build a custom action to query Github's API for the desired deployment. So let's start building!

Querying Github's API

First things first, we must come up with a query that will satisfy our needs. Github has 2 separate versions of their API, v3 which supports REST queries, and v4 which support GraphQL queries.

Both APIs support a very wide range of fields you can query, as well as actions that can be performed. From creating gists, to querying details about repository's contributors. You can really do a lot with the API. The documentation for v3 is found here, and the documentation for v4 is found here.

To our business, this is the query I've found to work best:

query($repo: String!, $owner: String!, $branch: String!) {
  repository(name: $repo, owner: $owner) {
    ref(qualifiedName: $branch) {
      target {
        ... on Commit {
          deployments(last: 1) {
            edges {
              node {
                latestStatus {
                  environmentUrl
                }
              }
            }
          }
        }
      }
    }
  }
}

I won't bore you with the details, those who wish to dive in deeper into Github's API can do it in the documentation.

What's important with this query is that it will fetch the latest deployment of the latest commit on our branch, which is exactly what we need. It also requires 3 parameters:

The name of the repo - $repo
The owner of the repo - $owner
The branch of which we want the deployment - $branch

You can go to Github's API explorer and run it with your parameters, and the result would look something similar to this:

{
  "data": {
    "repository": {
      "ref": {
        "target": {
          "deployments": {
            "edges": [
              {
                "node": {
                  "latestStatus": {
                    "environmentUrl": "https://your-deployment.some-domain"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

Well, great. Now we can fetch the latest relevant deployment from our repository, all we need is to utilise it. We can, obviously, just send a fetch request in the beginning of our test suite and get the result, but what if we need it for more than one step? Plus, it's not nearly as much fun.

Creating a Github Action

Now comes the fun part. Let's create the actual action so we can consume it in our workflow.

A Github Action is composed of 2 important parts - an action.yml file that contains metadata about the action, and an entry point.

Start off by initializing a new repository, or cloning a new one:

git clone https://github.com/your-name/your-action.git

Creating an `action.yml`

Let's continue with the action.yml. This file contains general information about our action, such as name and description, and how your action should run.

In our case we're using node.js in version 12, and our entry point in index.js. Later we'll see how to add inputs and outputs to our action.

name: "Hello World"
description: "Greet the world"
runs:
  using: "node12"
  main: "index.js"

Creating the main entry point

Now we need to create the index.js file we've specified in our action.yml. Luckily, Github provides two packages that will come in handy for writing our action: @actions/core and @actions/github.

From the docs:

The toolkit @actions/core package provides an interface to the workflow commands, input and output variables, exit statuses, and debug messages.

The toolkit also offers a @actions/github package that returns an authenticated Octokit REST client and access to GitHub Actions contexts.

You can go ahead and install them, we'll use them later on.

npm i @actions/github @actions/core

The most basic index.js can look like this:

console.log("Hello World!");

But we want it to be slightly more productive than that, and for that we need to define our action's inputs. Add the following lines to your action.yml:

name: "Get Deployment URL"
description: "Get the URL of the last deployment on a given branch"
inputs:
  token:
    description: "GitHub token"
    required: true
runs:
  using: "node12"
  main: "index.js"

We've now added a required input named token. The token is, as described, a token for authenticating with GitHub's API. Later I'll show you how to make sure the right token is passed to your action.

Let's make some use of this token in our index.js:

import { getInput } from "@actions/core";
import { GitHub } from "@actions/github";

const octokit = new GitHub(getInput("token", { required: true }));

The getInput utility function allows us to access inputs passed to the action. Later we'll see exactly how to pass them. The octokit variable is an authenticated REST client. We will use it to query Github's API.

Fetching the deployment in our action

Like I said earlier, to query the deployment we need 3 parameters - repo, owner and branch. All of those values are provided for us by Github, without us having to do much work.

For our owner and repo params, we can extract them from the GITHUB_REPOSITORY environment variable like so:

const [owner, repo] = process.env.GITHUB_REPOSITORY.split("/");

Getting the branch name is a little more tricky, here's how I ended up doing it:

const branch =
  process.env.GITHUB_HEAD_REF ||
  process.env.GITHUB_REF.match(/(?<=refs\/heads\/).+/g)[0];

You can get the full list of available environment variables here.

Now we just need to combine the query with our authenticated client. Create a file called query.gql and export the query from it like so:

module.exports = `query($repo: String!, $owner: String!, $branch: String!) {
  repository(name: $repo, owner: $owner) {
    ref(qualifiedName: $branch) {
      target {
        ... on Commit {
          deployments(last: 1) {
            edges {
              node {
                latestStatus {
                  environmentUrl
                }
              }
            }
          }
        }
      }
    }
  }
}
`;

And our index.js file will look like this:

import { getInput } from "@actions/core";
import { GitHub } from "@actions/github";
import query from "./query.gql";

const [owner, repo] = process.env.GITHUB_REPOSITORY.split("/");
const branch =
  process.env.GITHUB_HEAD_REF ||
  process.env.GITHUB_REF.match(/(?<=refs\/heads\/).+/g)[0];

async function run() {
  const octokit = new GitHub(getInput("token", { required: true }));
  const args = { repo, owner, branch };
  const result = await octokit.graphql(query, args);
}

run();

Pay it forward

Our job is not yet complete. In order to consume our deployment URL, we must set it as an output. First we must declare so in our action.yml:

name: "Get Deployment URL"
description: "Get the URL of the last deployment on a given branch"
inputs:
  token:
    description: "GitHub token"
    required: true
outputs:
  deployment:
    description: "The url of the most recent deployment"
runs:
  using: "node12"
  main: "index.js"

And now we can safely export it:

import { getInput, setOutput } from "@actions/core";
import { GitHub } from "@actions/github";
import query from "./query.gql";

const [owner, repo] = process.env.GITHUB_REPOSITORY.split("/");
const branch =
  process.env.GITHUB_HEAD_REF ||
  process.env.GITHUB_REF.match(/(?<=refs\/heads\/).+/g)[0];

async function run() {
  const octokit = new GitHub(getInput("token", { required: true }));
  const args = { repo, owner, branch };
  const result = await octokit.graphql(query, args);
  const deployments = result.repository.ref.target.deployments;
  setOutput(
    "deployment",
    deployments.edges[0].node.latestStatus.environmentUrl
  );
}

run();

Error Handling

But what if our action fails? What if we fail to authenticate with Github's API? What if we suddenly get a null?

For that we can use the setFailed function from @actions/core:

import { getInput, setOutput, setFailed } from "@actions/core";
import { GitHub } from "@actions/github";
import query from "./query.gql";

const [owner, repo] = process.env.GITHUB_REPOSITORY.split("/");
const branch =
  process.env.GITHUB_HEAD_REF ||
  process.env.GITHUB_REF.match(/(?<=refs\/heads\/).+/g)[0];

async function run() {
  try {
    const octokit = new GitHub(getInput("token", { required: true }));
    const args = { repo, owner, branch };
    const result = await octokit.graphql(query, args);
    const deployments = result.repository.ref.target.deployments;
    setOutput(
      "deployment",
      deployments.edges[0].node.latestStatus.environmentUrl
    );
  } catch (error) {
    setFailed(error.message);
  }
}

run();

Now we can be sure the correct status is reported when our action throws an exception.

Committing `node_modules` to git

Our last step is to commit the node_modules folder. Yeah I know what you're thinking. Take a deep breath, we'll go through it together.

The reason we do it is that when we run our action, Github does not allow us to run any sort of build script, so we can't install them when the action is ran.

To add you node_modules to git run the following commands:

git add node_modules/*
git commit -m "adding node_modules 😢"
git push

Those who want to avoid pushing your node_modules to the repo can use the excellent ncc compiler.

Putting everything together

Now all that's left is to use our action.

Open the repo you wish to add the action to, and add it as a step in your workflow file:

# ...the rest of you file
steps:
  # ...previous steps
  - name: Get deployment URL
    id: deployment
    uses: your-name/your-action-repo@master
    with:
      token: ${{ secrets.GITHUB_TOKEN }}

  - name: Run e2e
    run: npm run e2e
    env:
      deployment: ${{ steps.deployment.outputs.deployment }}
  # ...following steps

Do note that we're passing ${{ secrets.GITHUB_TOKEN }} as a token input to our function. This tells Github to pass a special token that is kept in secret, so no snooping eyes will be able to get it and authenticate with our credentials.

Now your deployment will be exposed as an environment variable to you test suite, and you will be able to access it with process.env.deployment.

That's pretty much it. Obviously there is a lot more you can do to perfect this action, you can add retry capabilities, rate limit handling and more.

There is also a lot more you can with Github actions in general. You can put them on the Github Action Marketplace for everyone to find, you can add logs, logo and branding and more. The sky is the limit when it comes to things like that.

If you don't want to go through the hassle of creating the action, I've published an action that does exactly that for my own personal use. It should work with any Github integration that creates Deployments with Github's API, and supports retries, rate-limiting and error handling. You can find it here.

Thank you for reading, I hope you've learned something and found my article useful.

I've made a GitHub action to get deployment URL on pull requests

Dor Shinar — Thu, 07 May 2020 19:45:30 +0000

My blog is hosted on Vercel (formerly Zeit Now), and while Vercel does a great job deploying my blog on every change (which in itself is super convenient), I could not figure out how to run tests against said deployments.

I've explored GitHub actions previously, and even wrote about it here, so I was familiar with the concept, but it still baffled me, so I've decided to give up on it and just run a local server as part of my CI pipeline.

Some months past, and I've had more time to experiment with it, and what I ended up with was an action I wrote myself, to query GitHub's GraphQL API and get the deployment url as a step output, so I could consume it in later steps.

You can find the action on the GitHub Marketplace. Using it is very straight forward:

# Rest of your workflow.yml...

- name: Get deployment URL
  id: deployment
  uses: dorshinar/get-deployment-url@v1.0.0
  timeout-minutes: 5 
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

- name: Run end-to-end tests
  run: npm run test:e2e
  env:
    deployment: ${{ steps.deployment.outputs.deployment }}

# Rest of your workflow.yml...

The action should (hopefully) work with all CI pipelines, given that they use GitHub's Deployment API. Please note that the action waits for the deployment to complete, and so I added timeout-minutes to it, so it doesn't run for too long.

That all. I'm planning on writing a more technical article explaining exactly how I accomplished it, but I just wanted to share it with you.

A Guarded City with no Defensive Wall - My 2¢ on TypeScript

Dor Shinar — Tue, 18 Feb 2020 00:00:00 +0000

TypeScript is huge right now. It’s exploding in popularity - as of today, it has almost 10M weekly downloads from NPM, their repo has nearly 60K stars and it feels like everybody jumps on the bandwagon when it comes to static type checking.

I’ll start this article by saying I’m a huge fan of typescript, and type-checking in general. The first language I’ve learned was C#, but in my first professional role I’ve worked exclusively with Python 2.7, and I missed the auto-completion and the confidence I had writing C#.

After about three years writing python I’ve transitioned from mostly backend to full-stack, where I quickly found solace in typescript.

I’ve seen quite a few articles where TypeScript was talked about as “bringing C#-like features to JavaScript”, or something else in that sense. And the fact that Microsoft is the company behind both languages sure helped make that case.

I feel like comparing TypeScript and C# does both languages wrong, and I’ve wanted to express my 2¢ on the debate.

TypeScript is not Object-Oriented

C# is an object oriented language - everything is an object, a class instance etc. TypeScript is not. At least not by definition.

You can write OO code in typescript, in much the same way you can write JavaScript in an OO way:

export default class API {
  private url: string;

  constructor(url: string) {
    this.url = url;
  }

  send(): Promise<{ status: number }> {
    return fetch(this.url).then(res => res.json());
  }
}

And in JavaScript:

export default class API {
  constructor(url) {
    this.url = url;
  }

  send() {
    return fetch(this.url).then(res => res.json());
  }
}

Or you can write TypeScript in a functional way:

export function send(url: string): Promise<{ status: number }> {
  return fetch(this.url).then(res => res.json());
}

And in JavaScript:

export function send(url) {
  return fetch(this.url).then(res => res.json());
}

So, no one is forcing you to write in one paradigm or another, what’s more is that today almost all general purpose languages have picked up characteristics from both ends of the spectrum, so I believe the difference is not as stark today as it used to be.

TypeScript is not `C#`

TypeScript has a fundamentally different type system from C#. One can say it takes a much more modern approach, or simply has a more sophisticated type system.

Things like unions, intersections, string/numeric literals, mapped types and so on are not possible (to my knowledge) in a more traditional object-oriented language such as C#.

type Success = 200 | 201 | 202; // numeric literal
type Error = "General Error" | "System Error"; // string literal
type Result = Success | Error; // union - Result = 200 | 201 | 202 | "General Error" | "System Error"

type A = { a: number };
type B = { b: string };

type C = A & B; // intersection - type C = { a: number, b: string }

type ReadonlyC = { readonly [P in keyof C]: C[P] }; // mapped type

None of the examples above is possible is C#, and there are more examples like this. All of these features bring TypeScript much closer to JavaScript in terms of flexibility.

Or, if you choose - you can simply go with the any type - that behaves just like a regular JavaScript variable - it can be assigned to any variable, and any property/method is assumed to exist by the typescript complier (I should note the unknown type, which is better for such use cases).

A Guarded City with no Defensive Wall

So if TypeScript is so perfect, why did I choose to title this article the way I did, implying that TypeScript is not really as secure as it seems?

Well, the answer might be obvious to those who’ve written typescript before, but for those who haven’t I have a way to demonstrate it.

In the old days, when you wanted to protect your city you would build a tall and sturdy defensive wall. You would set guards all along the the walls, on the lookout to find anyone who seeks to harm the city.

Photo by Richard Clark on Unsplash

Inside the wall, your police will make sure to keep the city safe from it’s own citizens, making sure everyone is safe, and everyone obeys by the rules. However, the police is not an army, and will be of little help should a near by city declare war against you.

Back to our topic, typescript is much like the police inside the walls. Given that anyone who’s entered the city is cleared, the police will keep it things in check, making things expected and comfortable.

As long as you deal with code bits you fully own, and do not rely on external sources or outside packages, you’re good to go.

Take for example the following code:

function add(a: number, b: number): number {
  return a + b;
}

function sumOrThrowIfLowerThan(arr: number[], threshold: number) {
  const sum = arr.reduce(add, 0);

  if (sum < threshold) {
    throw new Error("Sum can't be lower than threshold");
  }

  return sum;
}

const arr = [1, 2, 3, 4];

console.log(sumOrThrowIfLowerThan(arr, 10)); // output guaranteed to be a number

Even though we perform no run-time validation, we can be very certain that out functions will not misbehave.

Since we have compile time values here only, we can ensure that our array will contain only numbers, and their sum will behave like we expect (unlike adding a number to a string: 1 + "1" === "11").

However, the real problem arises when our input comes from sources we can’t control, most notably fetch requests or a dependency.

If we modify the code just a little bit:

function add(a: number, b: number): number {
  return a + b;
}

function sumOrThrowIfLowerThan(arr: number[], threshold: number) {
  const sum = arr.reduce(add, 0);

  if (sum < threshold) {
    throw new Error("Sum can't be lower than threshold");
  }

  return sum;
}

(async function() {
  const arr: number[] = await fetch("https://example.com/").then(res =>
    res.json()
  );

  console.log(sumOrThrowIfLowerThan(arr, 10)); // Can we guarantee the output type??
})();

What happens here is instead of using fixed, compile time values, we’re retrieving our array from an external URL, and we assume the result to be an array of numbers.

This is a very dangerous assumption to make - we can’t guarantee that the result will in fact contain only numbers, or that it will even be an array at all!

What if all of a sudden our external URL will decide to return a string? Or a single number? We might have runtime errors such as:

Many people would stop, declare typescript not worthy of their time, or that it generates a false sense of confidence, and therefore should not be used in favor of vanilla javascript.

Fortifying Your City

So we now know that typescript has very serious loop holes. Or maybe they are not loop holes at all - typescript was never designed for runtime safety. However, there are other great tools that can help us validate returned values.

I won’t go into much detail, but the most noticeable examples are probably joi, yup and class-validator. There are others for sure, but choosing any of these will probably be good enough for most use cases.

Here’s the previous example, but with runtime validation:

function add(a: number, b: number): number {
  return a + b;
}

function sumOrThrowIfLowerThan(arr: number[], threshold: number) {
  const sum = arr.reduce(add, 0);

  if (sum < threshold) {
    throw new Error("Sum can't be lower than threshold");
  }

  return sum;
}

(async function() {
  const resultSchema = yup.array().of(yup.number());
  const arr = await fetch("https://example.com/").then(res => res.json());

  const isValid = await resultSchema.isValid(arr);

  isValid && console.log(sumOrThrowIfLowerThan(arr, 10)); // output is guaranteed again and the QA is happy again 👌
})();

Notice that we don’t need to use runtime validation for everything in our code - only the bits we can’t control in runtime.

My 2¢

This article turned out much longer that I thought it would be, but here is my 2¢:

It definitely takes more time to add runtime safety on top of compile time safety, and in the end it’s up to you and your team to decide whether any of them is worth your time.

I believe that each on it’s own is very powerful, but not enough, and it’s the combination of the two that can make a great fortress.

It’s also OK if you choose to rely solely on runtime validation, but in that case you would need to build a much higher wall, as your citizens might be up to no good.

Awesome Chrome Dev Tools Tips and Tricks

Dor Shinar — Mon, 10 Feb 2020 16:34:46 +0000

The Chrome Developer Tools are a super powerful suite of tools for developing web application. They can do so much, from very basic operations like traversing the DOM, to checking out network requests or even profiling your application's performance.

Among the big, everyday features they expose, there are quite a lot of gems to be found if you look deep enough. Features that might save you a click or two, and isn't that what we're all about here?

jQuery style DOM queries in the console
Copying an element's properties
Filtering network requests
Emulating different network speeds
Using Live Expressions in console
Emulating different devices
Forcing an element's state

jQuery style DOM queries in the console

jQuery is awesome. It has ruled the web for over a decade, with some statistics talking about more than 70% of the most popular web pages in the world running some version of jQuery in them. That's crazy for a library dating all the way back to 2006.

The most popular API jQuery provides is the $, used for selecting DOM elements. The Chrome dev tools console allows you to make use of that $ selector, and more. Under the hood, $ is an alias to document.querySelector().

For example, if you want to simulate a click on an element you can do:

Similarly, $$ is an alias to document.querySelectorAll():

There are a few more tricks up the $ sleeve. Sometimes, a selector might be too complicated to write by heart, or you just don't know a selector specific enough. If you pick an element in the Elements tab you can retrieve it with the $0 variable in the console:

The console goes even further, allowing us to access not only the last selection, but the last 5, in order. The selections are exposed through the $0 - $4 variables:

Copying an element's properties

The elements tab is a really useful tab. It stores our website DOM tree, it allows us to see the CSS applied to each element, and we can make changes to elements on the fly from it.

A really cool trick I've found is the ability to copy properties of an element (and not only properties) from the context menu.

For example, you can copy an element's selector:

This selector might not be specific enough, or too specific for production, but should make your life a little easier when debugging.

As you can see in the previous gif, the copy context menu hides a few more nifty things you can copy. You can copy the element's styles, JS path (document.querySelector(SELECTOR)) or XPath.

Filtering network requests

Sometimes, you work on a page that has a lot of requests. I mean, A LOT.

Working your way through all those requests can be difficult when you look for something specific. Thankfully, you can very easily filter the requests.

The filter toolbar has quick toggles for various request types, such as XHR/Fetch, stylesheets, JS scripts, images and more:

If you need to be even more specific, or you might find it quicker, you can just write a filter criteria in the filter input right above the toolbar to search in the requests' names:

Emulating different network speeds

Using the Network tab again we can test our site in various internet speeds. The default preset is online, and you'll enjoy the full bandwidth of your internet connection.

Beside online, there are a few more presets available: Fast 3G, Slow 3G and offline, which vary in upload speed, download speed and latency. If you need to emulate a different, more exotic speed, you can add your own profile through the Add... button:

Using Live Expressions in console

What are Live Expressions?

Live Expressions are expressions which evaluate constantly at the top of you console. Say, you want to track a variable's value over time. You can log it over and over and over again:

With Live Expressions, you can focus on your code, and let chrome do the monitoring:

This obviously applies for variables defined both in the console and in a script.

Emulating different devices

Those of us working on responsive applications must know the feeling where you work really hard to make a beautiful layout, only to see it misbehave on devices with different resolutions.

I'm not here to tell you about media queries, but a convenient way to test that they work.

When you click on the button that looks like a tablet and a phone, you'll see that your browser's viewport changes to reflect a different device dimensions.

You can choose a device from a list of presets containing various popular devices, such as iPhone X, iPad Pro, Pixel 2, Pixel 2 XL and more. The list is admittedly a bit outdated, but I think it's good enough for most cases.

If you can't find a device that fits your needs, you can set a custom resolution. As you can see, I've set a custom resolution to emulate a OnePlus 6 (which is my daily driver).

Forcing an element's state

Have you ever faced a situation where you wanted to play with an element's :hover-specific css, but every time you moved your mouse to the styles section in the dev tools the element was no longer hovered?

Well, the chrome dev tools exposes a nice way to lock an element's state, so you can fiddle with it's properties with peace. This way you can quickly toggle an element's :active, :hover, :focus, :focus-within and :visited properties:

Those are my tips and tricks I think everyone can benefit from.

Thank you for reading!
This article was previously published on my blog: dorshinar.me. If you want to read more content, you can check my blog as it would mean a lot to me.

Rectangular Speech Bubble with Pure CSS and HTML

Dor Shinar — Thu, 30 Jan 2020 15:33:14 +0000

Lately I’ve been tasked with creating something similar to a speech bubble, that looks like that:

As you can see, it’s a rectangle with an arrow sticking out on one side, and a border around it all. I’ll walk you through some of the things I’ve tried to do to achieve the desired effect, and how I’ve decided to do it eventually.

First things first, we must create our rectangular div:

<div class="content">
  <ol>
    <li>first thing</li>
    <li>second thing</li>
    <li>third thing</li>
  </ol>
</div>

It’s nothing fancy, just a regular div displaying an ordered list, so it won’t be changing much throughout this article.

My First Attempt

At first, I tried creating the triangle using thick borders on a div:

<style>
  .arrow {
    position: relative;
    width: 0;

    border-top: 1.5vh solid transparent;
    border-bottom: 1.5vh solid transparent;
    border-left: 1.5vw solid black;
  }
</style>

<div class="container">
  <div class="content">
    <ol>
      <li>first thing</li>
      <li>second thing</li>
      <li>third thing</li>
    </ol>
  </div>
  <div class="arrow"></div>
</div>

I’ve truncated parts of the CSS that aren’t relevant, and I’ll link the full source below.

This gave me an initial result that got me somewhat closer to what I tried to achieve:

If you scratch your head trying to understand why the arrow looks like that, take a look at the arrow with painted borders:

.arrow {
  position: relative;
  width: 0;

  border-top: 1.5vh solid #1ca086;
  border-bottom: 1.5vh solid #1ca086;
  border-left: 1.5vw solid black;
  border-right: 1.5vw solid black;
}

As the width of our arrow is 0, it takes no space at all, but having thick borders makes them take a triangular shape. By making the borders we don’t need transparent, we can make the div look like a triangle.

However, this still does not give me the desired result - the entire div is black instead of white, and it has no border!

My Second Attempt

In my second attempt, I tried to tackle it in a different way. I was thinking - what if I could use clip-path to make a triangle, and possibly use border to make the border I please?

.arrow {
  position: relative;
  width: 1.5vw;
  height: 3vh;
  background-color: black;

  clip-path: polygon(0% 0%, 100% 50%, 0% 100%);
  border: 1px solid #1ca086;
}

The short answer is that I’ve succeeded in making a triangle, however surrounding it with a border resulted in quite a funky outcome:

What happens here is that the clipping happens after the border is “painted”, so it is clipped away with the rest of the div, hence we get our funky border.

My Third Attempt

In my third and last attempt I’ve decided to go all-in and spare no expense. Leave no css property unturned. It started with a general idea to make an underlying arrow acting as the border - essentially surrounding the arrow itself.

Here’s the code:

<div class="container">
  <div class="content">
    <ol>
      <li>first thing</li>
      <li>second thing</li>
      <li>third thing</li>
    </ol>
  </div>
  <div class="arrow-container">
    <span class="arrow-body"></span>
    <span class="arrow-border"></span>
  </div>
</div>

:root {
  --arrowHeight: 3vh;
  --arrowWidth: 1.5vw;
}

.arrow-body {
  position: absolute;
  width: var(--arrowWidth);
  height: var(--arrowHeight);
  clip-path: polygon(0% 0%, 100% 50%, 0% 100%);
  background-color: white;
  top: 0.25px;
  left: -2px;
  margin-top: auto;
  margin-bottom: auto;
  z-index: 1;
}

.arrow-border {
  position: absolute;
  width: calc(var(--arrowWidth) + 0.5px);
  height: calc(var(--arrowHeight) + 0.5px);
  clip-path: polygon(1% 0%, 100% 50%, 1% 100%);
  background-color: black;
  left: -1px;
  margin-top: auto;
  margin-bottom: auto;
}

.arrow-container {
  position: relative;
  height: calc(var(--arrowHeight) + 0.5px);
}

Let me explain what goes on here as there are multiple aspects in play. First, we need 2 divs - one for the border and one for the arrow.

The border must be slightly taller and wider, as it must stick out from the top, bottom and right just a bit, hence the height: calc(var(--arrowHeight) + 0.5px); and width: calc(var(--arrowWidth) + 0.5px);.

Both the arrow and the border are positioned absolutely so they can overlap, with the arrow having z-index: 1 so it stays on top.

The border is clipped in a similar manner to the arrow, except we start clipping in 1% 0% rather than 0% 0%, and end in 1% 100% rather than 0% 100% so our border won’t be clipped completely at the edges.

The rest is just fine tuning the position so it looks as pixel perfect as possible, resulting in a nice, bordered arrow attached to our rectangle.

You can find the full source right here.

Thank you for reading!
This article was previously published on my blog: dorshinar.me. If you want to read more content, you can check my blog as it would mean a lot to me.

Continuous Integration with Github Actions and Puppeteer

Dor Shinar — Wed, 25 Dec 2019 07:25:02 +0000

Lately I’ve added continuous integration to my blog using puppeteer for end to end testing. My main goal was to allow automatic dependency update using Dependabot.

As my CI platform, I chose Github Actions, as it is super easy to work with, and it integrates beautifully with any Github repository you already have. The whole thing only took roughly two days of intermittent work, and I think the results are quite awesome.

I do want to give a shout-out to Nick Taylor, who published his article on the subject, and laid the ground work for my efforts here, so I encourage you to read his article as well.

My tech stack is quite different though. I chose puppeteer as my end-to-end framework for several reasons. The first is that it is written and maintained by the folks behind the chrome dev tools, so I’m guaranteed a life-time support (until Chrome dies out, which is not in the near future), and it is really easy to work with.

Another reason is that at home I’m working on a windows laptop with WSL (on which I’m running zshell with oh-my-zsh), and setting up cypress is quite a bit more difficult (although in our world nothing is impossible). Both reasons led me to choose puppeteer, and so far I’m not regretting.

End to end testing

End to end (or E2E) tests are different from other types of automated tests. E2E tests simulate a real user, performing actions on the screen. This kind of tests should help fill the blank space between “static” tests - such as unit tests, where you usually don’t bootstrap the entire application, and component testing - which usually run against a single component (or a service in a micro-service architecture).

By simulating user interaction you get to test the experience of using your application or service in the same way a regular user would experience it.

The mantra that we try to follow is that it does not matter if your code performs perfectly, as long as the button the user should press is hidden due to some css quirk. The end result is that the user will never get to feel the greatness of your code.

Getting started with puppeteer

Puppeteer has a few configuration options that make it really awesome to write and validate tests.

Puppeteer tests can run in a “head-full” state, i.e. open a real browser window, navigate to the site being tested, and perform actions on the given page. This way you - the developers writing the tests - can see exactly what happens in the test, what buttons are being pressed and what the resulting UI looks like. The opposite of “head-full” would be headless, where puppeteer does not open a browser window, making it ideal for CI pipelines.

Puppeteer is quite easy to work with, but you’ll be surprised with the amount of actions you can perform using an automated tool.

We’ll start with a basic scraper that prints the page title when we go to https://dorshinar.me. In order to run puppeteer tests, we obviously must install it as a dependency:

npm i puppeteer

Now, our basic scraper looks like this:

const puppeteer = require("puppeteer");

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto("https://dorshinar.me");
  console.log(await page.title());

  await browser.close();
})();

What we do here is very simple, we open the browser with puppeteer.launch(), create a new page with browser.newPage() and navigate to this blog with page.goto(), and then we print the title. There are a bunch of things we can do with the puppeteer API, such as:

Running code in the context of the page:

(async () => {
  await page.evaluate(() => document.querySelector(".awesome-button").click());
})();

Clicking on elements in the screen using a CSS selector:

(async () => {
  await page.click(".awesome-button");
})();

Making use of the $ selector (jQuery style):

(async () => {
  await page.$(".awesome-button");
})();

Taking a screenshot:

(async () => {
  await page.screenshot({ path: "screenshot.png" });
})();

There is a bunch more you can do with the puppeteer API, and I suggest you take a look in it before diving into writing tests, but the examples I’ve shown should give you a solid ground to build from.

Integrating puppeteer with Jest

jest is an awesome test runner and assertion library. From their docs:

Jest is a delightful JavaScript Testing Framework with a focus on simplicity.

Jest allows you to run tests, mock imports, and make complex assertion really easily. Jest is also bundled with create-react-app, so I use it often at work.

Writing your first Jest test

Jest tests are super easy to write, and might be familiar to those who know other testing frameworks, by utilizing it, test, describe and other familiar conventions.

A basic test could look like:

function subtract(a, b) {
  return a - b;
}

it("subtracts 4 from 6 and returns 2", () => {
  expect(subtract(6, 4)).toBe(2);
});

You can also group multiple tests under one describe, so you can run different describes, or use it for convenient reporting:

function divide(a, b) {
  if (b === 0) {
    throw new Error("Can't divide by zero!");
  }
  return a / b;
}

describe("divide", () => {
  it("throws when dividing by zero", () => {
    expect(() => divide(6, 0)).toThrow();
  });
  it("returns 3 when dividing 6 by 3", () => {
    expect(divide(6, 3)).toBe(2);
  });
});

You can, of course, create much more complicated tests using mocks and other type of assertions (or expectations), but for now that’s enough.

Running the tests is also very simple:

jest

Jest will look for test files with any of the following popular naming conventions:

Files with .js suffix in __tests__ folders.
Files with .test.js suffix.
Files with .spec.js suffix.

jest-puppeteer

Now, we need to make puppeteer play nicely with jest. This isn’t a particularly hard job to do, as there is a great package named jest-puppeteer that can comes to our aid.

First, we must install it as a dependency:

npm i jest-puppeteer

And now we must extend out jest configuration. If you don’t have one yet, there are a number of ways to do it, i’ll go with a config file. Create a file named jest.config.js in the root of your project:

touch jest.config.js

In the file we must tell jest to use jest-puppeteer’s preset, so add the following code to the file:

module.exports = {
  preset: "jest-puppeteer" 
  // The rest of your file...
};

You may specify special launch configuration in a jest-puppeteer.config.js file, and jest-puppeteer will pass this configuration to puppeteer.launch(). For example:

module.exports = {
  launch: {
    headless: process.env.CI === "true",
    ignoreDefaultArgs: ["--disable-extensions"],
    args: ["--no-sandbox"],
    executablePath: "chrome.exe"
  }
};

jest-puppeteer will take care of opening a new browser and a new page and store them on the global scope, so in your tests you can simply use the globally available browser and page objects.

Another great feature we can use is the ability of jest-puppeteer to run your server during your tests, and kill it afterwards, with the server key:

module.exports = {
  launch: {},
  server: {
    command: "npm run serve",
    port: 9000,
    launchTimeout: 180000
  }
};

Now jest-puppeteer will run npm run serve, with a timeout of 180 seconds (3 minutes), and listen on port 9000 to see when it will be up. Once the server starts the tests will run.

You can now write a full test suite using jest and puppeteer. The only thing left is creating a CI pipeline, for which we’ll use github actions.

You can add a script to your package.json file to execute your tests:

{
  "scripts": {
    "test:e2e": "jest" 
  }
}

Github Actions in a gist

Lately Github released a big new feature called Actions. Basically, actions allow you to create workflows using plain yaml syntax, and run them on dedicated virtual machines. In your workflow you can do pretty much anything you want, from basic npm ci && npm build && npm run test to more complicated stuff.

I’ll show you how to configure a basic workflow running your puppeteer test suite, and prevent merging if your tests don’t pass.

The easiest way to start is to click on the Actions tab in your github repo. If you haven’t configured any action before, you’ll see a list of previously configured workflows, from which you can choose one with some predefined configuration.

For our case, choosing the predefined Node.js action is good enough. The generated yaml looks like this:

name: Node CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [8.x, 10.x, 12.x]

    steps:
      - uses: actions/checkout@v1
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
      - name: npm install, build, and test
        run: |
          npm ci
          npm run build --if-present
          npm test
        env:
          CI: true

In the file you can configure the workflow name, jobs to run, and when to run the workflow. You can run your workflow on every push, on new pull requests or as a recurring event. Jobs in a workflow run in parallel by default, but can be configured to run in sequence. In the above workflow, there is one job named build.

You can also choose the OS on which your workflow will run (by default you can use Windows Server 2019, Ubuntu 18.04, Ubuntu 16.04 and macOS Catalina 10.15 - at the time of publish) with the runs-on key.

The strategy key can help us run our tests on a matrix of node versions, in this case we have the latest versions of the latest LTS majors - 8.x, 10.x and 12.x. If you are interested in that you can leave it as is, or simply remove it and use any specific version you want.

The most interesting configuration option is the steps. With it we define what actually goes on in our pipeline. Each step represents an action you can perform, such as checking out code from the repo, setting up node version, installing dependencies, running tests, uploading artifacts (to be used later or downloaded) and many more. You can find a very extensive list of readily available actions in the Actions Marketplace.

The basic configuration will install dependencies, build our project and run our tests. If you need more (for example if you want to serve your application for e2e tests) you may alter it to your liking. Once done, commit your changes and you are good to go.

Forcing checks to pass before merge

The only thing left for us is to make sure no code can be merged before our workflow passes successfully. For that, go to your repo’s settings and click on Branches:

We need to set a Branch protection rule so that malicious code (or at least one that doesn’t pass our tests) won’t be merged. Click on Add rule , and under Branch name pattern put your protected branch (master, dev or which ever one you choose). Make sure Require status checks to pass before merging is checked, and you’ll be able to choose which checks must pass:

Click on Save changes below, and you’re good to go!

Themes Using CSS Variables and React Context

Dor Shinar — Fri, 25 Oct 2019 13:05:33 +0000

CSS variables are really cool. You can use them for a lot of things, one of which is applying themes in your application with ease. In this tutorial I’ll show you how to integrate them with react to create a ThemeComponent (with context!).

CSS Variables in a Gist

So first of all, I’d like to explain briefly what CSS variables (or in their formal name - CSS custom properties) are, and how to use them.

CSS variables are a way for us to define variables, that will be applied throughout our application. The syntax is as follows:

What happens here?

Using the --{varName} notation we can tell our browser to store a unique variable called varName (or in the example above, primary), and then we can use it with the var(--{varName}) notation anywhere in our .css files.

Seems really simple? Because it is. There’s not much to it. According to caniuse.com over 92% of users world wide use a browser that supports css variables (unless you really need IE support, in which case you’re out of luck), so for the most part they’re completely safe to use.

If you want to read more, you can find more information in the MDN page.

Setting CSS Variables from Javascript

Setting and using CSS variables from javascript is just as easy as setting and using them in css. To get a value defined on an element:

const primary = getComputedStyle(element).getPropertyValue("--primary");

Will give us the value of the primary custom css property defined for the element.

Setting a custom css property works like so:

element.style.setProperty("--light", "#5cd2b6");

Or, if we want to set the property for the entire application, we can do:

document.documentElement.style.setProperty("--light", "#5cd2b6");

And now the light property will be accessible to all of our code.

React Context in a Gist

The React Context API is the only way provided by react to pass props indirectly from one component to a descendent component. In this guide I’ll use the useContext hook, which you can read more about here, but the principle is the same with class components.

First, we must initialize a context object:

import React from "react";

export const ThemeSelectorContext = React.createContext({
  themeName: "dark"
});

The parameters passed to the React.createContext function are the default parameters of the context. Now that we have a context object, we can use it to “inject” props to our indirect descendants:

export default ({ children }) => (
  <ThemeSelectorContext.Provider value={{ themeName: "dark" }}>
    {children}
  </ThemeSelectorContext.Provider>
);

And now anyone who wants to read the values in our context can do it:

import React, { useContext } from "react";
import { ThemeSelectorContext } from "./themer";

export const () => {
  const { themeName } = useContext(ThemeSelectorContext);

  return <div>My theme is {themeName}</div>
};

A Voila! No matter where in the component hierarchy our component lies, it has access to the themeName variable. If we want to allow editing the value in our context, we can pass a function like so:

export default ({ children }) => {
  const [themeName, setThemeName] = useState("dark");

  const toggleTheme = () => {
    themeName === "dark" ? setThemeName("light") : setThemeName("dark");
  };

  <ThemeSelectorContext.Provider value={{ themeName, toggleTheme }}>
    {children}
  </ThemeSelectorContext.Provider>;
};

And to use it:

import React, { useContext } from "react";
import { ThemeSelectorContext } from "./themer";

export const () => {
  const { themeName, toggleTheme } = useContext(ThemeSelectorContext);

  return <>
    <div>My theme is {themeName}</div>
    <button onClick={toggleTheme}>Change Theme!</button>
  </>
};

That’s enough for our needs, but if you want you can further read on the Official React Context Documentation.

Putting Everything Together

Now that we know how to set css custom properties from javascript, and we can pass props down our component tree, we can make a really nice and simple “theme engine” for out application. First up we’ll define our themes:

const themes = {
  dark: {
    primary: "#1ca086",
    separatorColor: "rgba(255,255,255,0.20)",
    textColor: "white",
    backgroundColor: "#121212",
    headerBackgroundColor: "rgba(255,255,255,0.05)",
    blockquoteColor: "rgba(255,255,255,0.20)",
    icon: "white"
  },
  light: {
    primary: "#1ca086",
    separatorColor: "rgba(0,0,0,0.08)",
    textColor: "black",
    backgroundColor: "white",
    headerBackgroundColor: "#f6f6f6",
    blockquoteColor: "rgba(0,0,0,0.80)",
    icon: "#121212"
  }
};

This just happens to be the color pallette I use for my blog, but really the sky is the limit when it comes to themes, so feel free to experiment.

Now we create our ThemeSelectorContext:

export const ThemeSelectorContext = React.createContext({
  themeName: "dark",
  toggleTheme: () => {}
});

And our theme component:

export default ({ children }) => {
  const [themeName, setThemeName] = useState("dark");
  const [theme, setTheme] = useState(themes[themeName]);

  const toggleTheme = () => {
    if (theme === themes.dark) {
      setTheme(themes.light);
      setThemeName("light");
    } else {
      setTheme(themes.dark);
      setThemeName("dark");
    }
  };

  return (
    <ThemeSelectorContext.Provider value={{ toggleTheme, themeName }}>
      {children}
    </ThemeSelectorContext.Provider>
  );
};

In this component we store our selected theme object, and the selected theme name, and we defined a function to toggle our selected theme.

The last bit left is actually setting the css custom properties from our theme. We can easily do it using the .style.setProperty API:

const setCSSVariables = theme => {
  for (const value in theme) {
    document.documentElement.style.setProperty(`--${value}`, theme[value]);
  }
};

Now for each value in our theme object we can access a css property with the same name (prefixed with -- of course). The last thing we need is to run the setCSSVariables function every time the theme is toggled, so in our Theme component we can use the useEffect hook like so:

export default ({ children }) => {
  // code...

  useEffect(() => {
    setCSSVariables(theme);
  });

  // code...
};

The full source can be found on github.

Using our theme is super convenient:

.title {
  color: var(--primary);
}

And updating our theme is just as easy:

import Toggle from "react-toggle";

export default () => {
  const { toggleTheme, themeName } = useContext(ThemeSelectorContext);

  <Toggle defaultChecked={themeName === "dark"} onClick={toggleTheme} />;
};

For this example I’m using the Toggle component from react-toggle, but any toggle/button component would do just fine. Clicking the Toggle will call the toggleTheme function, and will update our theme for the entire app, no more configuration needed.

That’s it! That’s all you need to do to create a super simple, super clean theme engine for your application. If you want to see a real live example, you can check out the source code of my blog.

Thank you for reading and I hope you enjoyed it!

Be The Perfect Teammate!

Dor Shinar — Thu, 12 Sep 2019 00:00:00 +0000

I bet your all have had a teammate in the past you could not stand. Each with his/her own reasons, maybe you didn’t like their professional capabilities, the way their breath smelled in the morning or the inappropriate jokes they made during serious meetings. On the other hand I bet you’ve had people in your teams who you’ve felt like they’re such a positive addition to the team, that you can’t remember being without them. I’ll try to list some things here that I think can make someone a better teammate.

Learn To Listen

Photo by Mohammad Metri on Unsplash

Being a good listener is the first thing I’d think of when I think of a good teammate. No one likes stubborn people who are always so sure of their ways. You might be the most experienced developer by a lot on the team. It does not mean you know everything. You can’t know everything.

In some scenarios you are obligated to listen to someone else’ opinion, whether it’s your team lead, upper management or the product department, but those are not the times your listening skills are being judged. You are judged in front of your peers, employees, or anyone else who’s in the same position as you or beneath you.

This definition applies both for senior, seasoned and experienced engineers you work with, or juniors in the beginning of your career. Being a junior, it sure feels nice when a senior listens to what you have to say, and even more when they accept your opinion.

Everyone Can Teach You Something

Photo by NESA by Makers on Unsplash

I know it’s fun to laugh at the newby who suggests a complete refactor on the first day at the job. He obviously does not know the struggles you’ve been through trying to get the code up and running. He did not wake up at night while being on-call, and he never nearly broke a chair after an elusive bug you couldn’t solve.

All those experiences you’ve had ultimately led you to create the product you have today. That is nothing to ridicule, belittle or insult. However, somethings are easier to see with a fresh pair of eyes, things you’ve overlooked, got used to or simply never prioritized. New people, new insights, so even if they speak balderdash, it should be worth hearing, at the very least.

Incapable Teammates Can Wreak Havoc

Photo by Stella Caraman on Unsplash

No one can be good at everything at once, certainly not when they are inexperienced. But you should always aspire to be the best you can. If you don’t, your teammates might feel like you’re dragging them down, slowing the team or generally being of little help.

If you feel like you’re in that position (not to be confused with impostor syndrome, which is a separate issue altogether), you have plenty of courses of action. The best advice I can give, by far, would be to simply ask for help. Find someone you trust, and think they represent a good role model for you, and ask them how they got to this position. What have they done along the way to be what they are, and what can you do as well.

There are plenty of things you can do, regardless of what your mentor will advise you. You can educate yourself (either via reading articles, or taking courses in sites like Udemy or coursera), practice at home (personal projects are a great place to start, contributing to open source projects is another)

If you feel like you’re on the opposite side, being the senior engineer and have an inexperienced engineer drag you down, it should be your goal to lift them up. They might not even be aware that they are not living up to their full potential, and it is your job to show them what they can achieve. Offer pair programming sessions, advices or technological resources to help your teammate improve over time. Just don’t do it in a condescending way, as you don’t want to intimidate or offend anyone. Plus, no one likes a show off.

You Don’t Have To Be The Best Developer On The Team

Photo by Chris Liverani on Unsplash

It’s OK if you’re not the sharpest tool in the shed. There will usually be that one person who’s forever in the company, knows every bit of code in the system and can identify problems before you even get a chance to look at the logs. It’s OK. Most companies will guide you and mentor you, so you can always be better than yesterday. I’d even go as far to say that if you are in a position where you don’t feel progress, get up and leave. We’re blessed to work in a very desirable field, and job opening are quite easy to find.

My main point is that you shouldn’t be scared or worried about your status. Becoming a senior engineer takes time and practice, so don’t rush things and just focus on your personal growth.

Being in the middle is actually quite a good place to be. You can learn from those you feel are more experienced, and you can teach people who are new in the company and new to coding in general. I firmly believe that teaching is the best way to learn something - it compels to have a really strong understanding of a subject so you don’t confuse or misinform others.

First Impression Matters, But Second Impression Lasts

Photo by Isaac Smith on Unsplash

You first day often seems the most important one, a day that will mark the rest of your time in the company. On this day people will see you for the first time, talk to you and judge you. This day can be very nerve wracking. You don’t want to misspeak, so people won’t think you are a fool, or that you are not professional. You also don’t want to spill coffee on your shirt and look like the office dork.

I say - that’s wrong. If, on average, an engineer stays in his position for about 3 years (give or take), that means that you will have about 365*3-1=1094 days to make amends for the first impression. Don’t fret, it’s OK to make mistakes, those mishaps will become something to joke about with your peers later on, when they get to know the real you.

Of course, and I hope this goes without saying, a bad second impression (and third, fourth and so on) can completely ruin a good first impression, so watch out for that too. As I’ve said, no one likes a co-worker with a stinky breath, or one that makes rude comments.

Summing Up

Those were my thoughts on what would make a good teammate. I think a good teammate must have good listening skills and willingness, and you must know that everyone can and will teach you something. A good teammate also doesn’t have to be the best ninja out there, and doesn’t have to make the best first impression, but you will have to make up for a lousy one.

Thank you for reading, I hope you liked it!

Cover image by Perry Grone on Unsplash

Building a Personal Blog

Dor Shinar — Wed, 26 Jun 2019 19:46:00 +0000

It all started from the beginning of 2019. It was a gloomy day at the office as I was struggling to get ESLint and Prettier to work nicely with React and Typescript. After battling with it for a couple of hours, I’ve decided to write an article about it.

Time moved on and I’ve written a couple more (even though neither of them got the traction of the first, beginners luck I guess). I’ve started to really like the concept of writing articles. I’ve started getting more into the world of publishing technological articles. A lot of buzzwords were thrown in the air - cross-posting, search engine optimization, canonical links and more. I’ve noticed that most of the serious people who post articles have a blog of their own from which they share (or cross-post, as the lingo goes) to other platforms.

I was thinking to myself - Why shouldn’t I have one? You could say it’s not really worth the hassle, as I don’t have a clear vision as to how many articles I plan to write, and I certainly don’t have the time to write every week or so, but I thought it would be a fun project, and I hoped to learn something from it.

Hint - that’s the end result:

I have a decent experience with web development, mostly in React and I was thinking I could make a use of it in my blog. Around that time I stumbled upon this post:

Do you have your own Gatsby site? Let's brainstorm a dev.to cross-poster

Mike Bifulco ・ Jun 22 '19 ・ 2 min read

#react #discuss #opensource #productivity

where the author suggested using Gatsby.js for such things. I’ve never worked with Gatsby before, and most of my experience in web development comes from the component age (quite a noob, I know), but after a quick look through the documentation (which is superb!) I figured it would be a perfect solution for my blog.

Let’s Build a Blog

I’m not going to explain every little implementation details (this is not a Gatsby tutorial) - mostly because I feel everything I can write wouldn’t be as clear as the official docs.

I started by going through Gatsby’s step-by-step tutorial. And after getting a good-enough grip on the matter, I’ve decided to jump right in. I used a starter built for blogs by gatsby (it’s right here!), which gave me a solid skeleton to begin with. I know I could’ve made it myself, but I didn’t feel confident enough with gatsby, so I considered it a template - much like projects bootstrapped with Create React App and I know there is a big debate over whether these starters are the best way to go, but this is not the scope of this post.

Generating a Base Line

First things first, I’ve removed some bloat I didn’t need and replaced it with my own articles and profile pic. The next thing I did was format my posts. Now that I was using a starter (which relies on good markdown practices), I’ve found out that my articles were not up-to-snuff - for example - missing subtitle, description et cetera. The whole point of frontmatter was new to me - Medium and dev.to do a great deal in helping you avoid that.

Another thing I added was a reading time measure (Don’t you just love to see an estimate to how long it would take you to read a post?).

Ready to push and deploy

Just kidding, obviously it was not done yet (for my likes, other people might find it satisfactory at this stage), but it really took little effort on my side to make it very functional with my own data.

A few more minor modifications took place - I added links to my GitHub and Linkedin profiles (a few more were added later). I’ve also started writing this very article, as I wanted it to be written more as a blog post describing the process rather than a technical article about setting up a gatsby site.

I’ve converted all the inline CSS to Styled Components, as I simply love the way SC enables you to write semantic HTML in a way that suites each and every component in your code. ESLint + Prettier + Husky + Lint Staged were a welcome addition as well at this stage, as it drove me nuts to manually fix code and style errors. A custom scroll indicator and shorter post URIs (or slugs) were the last addition at this stage.

CSS Tweaks FTW

My journey continued with A LOT of small tweaks, mostly around CSS and visibility - using a google font, line breaks between posts, and extracting the Header to a new component. Nothing big, but those tweaks helped me down the line, and made the site look slightly better.

I’m a huge fan of dark mode. My agenda is “Dark Mode ALL THE THINGS!”, so naturally I couldn’t let my website sit idly by with only white background. I started implementing a theme switcher (using Context and styled-components’ ThemeProvider). At the beginning it was a simple button to switch black and white background, and as I got is up an running I created a full color scheme for my website, both for a light theme and a dark theme. (Shout out to Google’s Material Design Dark Theme Documentation). All my referral icons had to be converted based on the theme, so that happened as well, and my theme was nearly complete (it has undergone some small hue tweaks later but whatever).

Fitting my website to look best on mobile was the next step - as I am used to develop enterprise apps mostly for desktops, it slipped my mind that most traffic today comes from mobile. From the W3C’s Responsive Web Design - Media Queries tutorial

Always Design for Mobile First

So I failed in that until now, but I was eager to change that. Using Google Chrome’s awesome developer tools is was really easy to simulate a bunch of different devices at different sizes and resolutions, so more CSS tweaks took place.

In an effort to make the site ready for going live, I’ve added a link to the RSS feed, that was generated (the starter I am using took care of that).

Deploy Like You Just Don't Care

Now I really felt confident I could upload it to the cloud for the world to see. Knowing there will be no traffic at the beginning, I knew I can experiment after setting it up, so I left some things for later. The cloud provider I chose was Now, as I saw a this post:

Heroku, Now.sh, Netlify. What are you using and why?

Daniel Crewdson ・ Jul 24 '19 ・ 1 min read

#javascript #node #cloud

where quite a lot of people recommended it, so I figured I’d take a look at their offers. My blog is strictly a hobby, and I don’t plan on monetizing it, so I was looking for something with a free tier that would fit my needs, and after comparing the offerings of Netlify and Now, I’ve decided to go with Now.

Setting it up with my Github account was super easy, and everything just worked, as I expected. I bought a domain and registered it there, and I’m off to the races.

Now.sh integrates really well into Github, so it redeploys on every push, saving me a few clicks, and the overall UI feels very intuitive, allowing me to get up and running in less that an hour.

The last few things I had to do were setting up analytics (first time for me as well), adjust links to point to my flashy new domain and fix some small a11y stuff (I don’t want to keep anyone from reading my blog), allowing me to get awesome scores in lighthouse tests (YAY!).

Now my site is up and running, and all that is left is make sure it appears in search results (canonical URLs and all that), and marvel on almost 2 months of work. It sounds like a lot but I only had a few hours here and there to actually work on it. If I was doing it full time it probably would have taken 2-3 week, or even less.

For me it was a real learning experience, coming from enterprise background (where we run in a closed intranet for security reasons). I got to try a bunch of cool stuff and build something that I find really awesome. Now my plan is to keep writing whenever I get the chance, so more people will be exposed to my articles.

The blog is obviously not complete. I suppose I’ll add integrated commenting mechanism sometimes soon, and a bunch of other stuff like links to editing on github, but for now I’d say it’s definitely good enough.

Thank you for reading!

Why I've Stopped Writing Snapshots Tests in Jest

Dor Shinar — Tue, 18 Jun 2019 18:40:07 +0000

Why I've Stopped Writing Snapshots Tests in Jest

And why I think you should stop too

I'm developing a frontend application for quite a while now, and my team and I have a strict standard regarding unittesting out features - every new feature must be thoroughly tested with unit tests (Jest + Enzyme for our client, which I'll be talking about in this article).

It took us a while to find the right path for us, all while learning how to use the tools we've chosen to the full extent, but through trial and error we've found a paradigm that works for us.

One of the first things you learn when reading Jest's documentation is how to write Snapshot Tests. They are meant to be the ultimate testing utility, and they interact beautifully with React components. You can "render" a component in your test under some condition, save it to a snapshot, and if in any future test the output of the component changes the test will fail and tell you that you've changed something you probably shouldn't have, and if you did it on purpose, you simply update the snapshot to reflect the new state of the component. For the purpose of this article I will explain the snapshot process briefly, but this is not an educational article - I strongly recommend the documentation of Jest for that.

In practice, it goes something like this - let's create a super simple component that look something like this:

A simple test for it might be something along the lines of:

When we first run the test, it passes and creates a new snapshot. The snapshot looks like that:

Not too complicated as it is a super simple component I wrote in 2 minutes.

Let's say time passes and the component changes. It now looks like this:

My component obviously changed (I'm the one who changed it). Running the test now would result in a failed test, as the snapshots don't match, so I'm forced to update the snapshot to reflect the new state - basically forcing my test to pass.

Now that we have a basic understanding of snapshot testing I can make some bold claims as to why I have stopped using them entirely, and why I think you should too.

It's really hard to be specific as to what your test is actually testing. You can get away with that writing very small tests and have very descriptive names, but at that time I feel like a designated test for a specific use-case would be clearer, easier to maintain over changing demands and less fragile to irrelevant changes in your component.
Constant updating of snapshots can create an "if-it-doesn't-pass-just-update-it" attitude, especially when there are dozens of snapshots failing at once, and you/your teammate might be too lazy to actually task a closer look at each and every one of the failing tests, so updating them all becomes nearly automatic.
They provide no helpful information as to how the code is used, and how it should behave. They merely show what is rendered in a given situation, without any concrete assertions to help future you/new developers understand why or how the magic of your components happens.

This is my personal opinion on the subject, I'd love to hear different opinions about snapshot testing (not only in jest). Do you still write them? Have you found some enlightenment that I haven't? Please share!

I am a Great Software Developer

Dor Shinar — Wed, 15 May 2019 15:38:51 +0000

My thoughts and opinions on how one can become a better software developer.

Well, I’m not THAT much a narcissist as the title implies. In fact, I’m not nearly as good as I wish I was. I only have a few years of experience under my sleeve, but I have gathered some helpful insights that help me get better everyday.

I believe that if you follow them you can definitely step up your game. It doesn’t have to be all at once — slowly and steadily adopt some parts of it, in whichever pace fits you.

Always Be Better Than Yesterday

Try to think of the last time you’ve actually done something you learned from. Something that made you better than the day before.

Photo by Jungwoo Hong on Unsplash

If you can’t recall the last time you’ve read something interesting, or done something out of the ordinary you should be worried. I believe that if you are here, reading my article then you are the type that loves to better themselves, even if not on a daily basis.

There are oh-so-many ways to be better everyday, but the most fundamental is learning new things as often as possible. Medium (and other platforms) are filled with information, guides and walkthroughs to help you do awesome things, whichever technological stack you or your company chose.

Let’s say you’ve heard from a co-worker of yours about that sweet sweet new feature in [Some-Super-Awesome-Framework]. Sadly, most developers I know will go “yeah that sure sounds nice, but I bet it’s complicated so I shouldn’t even try”. Whether it’s from laziness, low self-esteem or lack of time, I can safely say, this statement is wrong more often than not. Most likely the technologies you chose are maintained by responsible teams, or avid communities (and if not, then maybe you should reconsider them), and most features (complicated or not) would have awesome guides to help you through.

Don’t fear the unknown. The worst thing that can happen is that you will fail to implement said feature and learn for the future. I’ve yet to fail without learning anything new. And let’s not forget the happy scenario where you succeed — you got to learn something and made your/your team’s/your company’s code better and more maintainable, and isn’t that what we’re all about?

I think the best thing you can do is adopt a habit of reading at least one article every day. I regularly use Pocket (I’m not affiliated with them in any way) to store articles I find in different sources, so I always have a list of articles waiting for me, and whenever I get the time I open the app and catch up on them. You can choose whichever method that works for you (for example, I’ve also trained my Google feed to show me a lot of tech oriented articles), but make sure you do it, and it should be as easy as possible.

Don’t Focus Only On “Your Code”

To be honest, I hate it when people refer to parts of the code as their own.

“This is my feature, only I am allowed to make changes to it”

and the opposite:

“This is not my feature, so if it breaks it is not my responsibility”

or worse:

“I didn’t write this code, so there’s no reason for me to touch it”

The code doesn’t belong to anyone, and it works both ways. You should know as much as possible about as many aspects of your system as possible. Of course I don’t expect anyone to know by heart every micro-service in a system that contains hundreds of them, with barely a dozen maintained by their team, but that’s what you should aspire to.

You should know how your app is deployed, rather than simply relying on it to work. Get to know your CI/CD pipeline, environments used, scripts used to run your application. If you use some form of logs analyzing tool (and you should), get to know how to query it and how to create dashboards, even if no-one will look at them, as that might be useful in the future. I would also consider in this category some basic things that exist in any application — user authentication, database interactions and so on.

You might even want to get people to explain to you about things they’ve done in the code base, so you don’t have to figure everything out by yourself.

You don’t have to master every aspect of your system, nor should you be a jack-of-all-trades (and master of none). You should have an area of expertise, just make not you don’t neglect other areas. Some people would call this a T shaped person, where the top bar of the T represents the broad but shallow knowledge, and the long “foot” of the letter is your area of expertise.

Don’t Fear Reading Other People’s Code

We read code a lot more than we write. Period.

Photo by Pankaj Patel on Unsplash

Usually this line opens a paragraph (or an article) about writing clean code or using some documentation format. While those things are very important, and no application would succeed without close attention to them, I would like to put an emphasis on the reading part, rather than the writing part. Reading other people’s code can do wonders for you — it can open your mind to creative ways to achieve a certain goal or a feature, you can find weak spots in the code base (ones you’d like to fix later, or simply inform your team) and make you a better developer in general.

You should also aspire to review people’s code as often as possible (I know it can be a hassle for some people, but trust me it’s worth it).

At work I was in charge (along with other brilliant people) of the bootcamp for new recruits. Over the course of 4 months I was tasked with A LOT of code reviews, meant to make sure that their code meets the standards of the company. Looking at the recruits from the beginning to the end surely showed a massive improvement in their abilities (otherwise it would be a colossal waste of time🙃), but as a side effect I felt like I was getting better as well, even thought I barely had a chance to write code.

I think the main takeaway here is that you shouldn’t be afraid of foreign code. It will exist where ever you choose to work. Embrace it, learn from it, and improve it from time to time.

To sum up, here’s the gist:

Always be better than yesterday
Don’t focus only on “your code”
Don’t fear reading other people’s code

Those are my two cents on how to be a better software developer. I hope you liked it (only my second article on Medium!). You are more than welcome to comment your opinion (I love a good discussion).

Thank you for reading!

DEV Community: Dor Shinar

Avoiding impossible state with TypeScript

Impossible State

Naïve solution

A better way

One interface to rule them all? No

Embracing difference

Summary

Creating Custom Github Actions is Easy!

Querying Github's API

Creating a Github Action

Creating an action.yml

Creating the main entry point

Fetching the deployment in our action

Pay it forward

Error Handling

Committing node_modules to git

Putting everything together

I've made a GitHub action to get deployment URL on pull requests

A Guarded City with no Defensive Wall - My 2¢ on TypeScript

TypeScript is not Object-Oriented

TypeScript is not C#

A Guarded City with no Defensive Wall

Fortifying Your City

My 2¢

Awesome Chrome Dev Tools Tips and Tricks

jQuery style DOM queries in the console

Copying an element's properties

Filtering network requests

Emulating different network speeds

Using Live Expressions in console

Emulating different devices

Forcing an element's state

Rectangular Speech Bubble with Pure CSS and HTML

My First Attempt

My Second Attempt

My Third Attempt

Continuous Integration with Github Actions and Puppeteer

End to end testing

Getting started with puppeteer

Integrating puppeteer with Jest

Writing your first Jest test

jest-puppeteer

Github Actions in a gist

Forcing checks to pass before merge

Themes Using CSS Variables and React Context

CSS Variables in a Gist

Setting CSS Variables from Javascript

React Context in a Gist

Putting Everything Together

Be The Perfect Teammate!

Learn To Listen

Everyone Can Teach You Something

Incapable Teammates Can Wreak Havoc

You Don’t Have To Be The Best Developer On The Team

First Impression Matters, But Second Impression Lasts

Summing Up

Building a Personal Blog

Do you have your own Gatsby site? Let's brainstorm a dev.to cross-poster

Mike Bifulco ・ Jun 22 '19 ・ 2 min read

Let’s Build a Blog

Generating a Base Line

Ready to push and deploy

CSS Tweaks FTW

Deploy Like You Just Don't Care

Heroku, Now.sh, Netlify. What are you using and why?

Daniel Crewdson ・ Jul 24 '19 ・ 1 min read

Why I've Stopped Writing Snapshots Tests in Jest

Why I've Stopped Writing Snapshots Tests in Jest

I am a Great Software Developer

My thoughts and opinions on how one can become a better software developer.

Always Be Better Than Yesterday

Don’t Focus Only On “Your Code”

Don’t Fear Reading Other People’s Code

Creating an `action.yml`

Committing `node_modules` to git

TypeScript is not `C#`