DEV Community: David Losert

Mock-Factory-Pattern in TypeScript

David Losert — Mon, 12 Jul 2021 14:24:40 +0000

If you are writing automated tests (and I sure hope you do), you most likely also create a lot of mock-data to feed into the functions under test. With this post I want to show you how to do this in a scalabe, reusable and focused way by using a mock-factory.

The initial simple way

When starting a new project or test-suite, creating mock-data usually starts out very simple by using object literals:

it('markTodoAsDone sets done to true.', () => {
  const unfinishedTodo: Todo = {
    title: 'Write an awesome post about Testdata-Patterns',
    done: false
  };

  const resultingTodo = markTodoAsDone(unfinishedTodo);

  assert.deepStrictEquals(resultingTodo.done, true);
})

However, as your project grows, your data usually grows as well. New properties and behaviours are added, and you will quickly realize that the method above does not scale well. Everytime a new property is introduced, you have to revisit every single test and adjust the testdata-object. Depending on the size of your project, that might be a dozen or even hundreds of required adjustments because of a single change.

But the example above actually has another issue - can you spot it?

Maybe it becomes clearer once we actually add some new properties:

it('markTodoAsDone sets done to true.', () => {
  const unfinishedTodo: Todo = {
    title: 'Write an awesome post about Testdata-Patterns',
    done: false,
    dueDate: new Date('2021-07-04'),
    assignee: 'David Losert',
    project: 'Writing Blogposts',
    tags: ['writing', 'blogs']
  };

  const resultingTodo = markTodoAsDone(unfinishedTodo);

  assert.deepStrictEquals(resultingTodo.done, true);

Right, with pure object literals you actually have to specifiy all the properties of the object all the time - even if only one of those is relevant for the unit under test. That is a lot of distraction. Tests should be precise, focused and only contain the data and properties currently required.

Alternative ways

So what is the alternative, you might ask? I have seen quite some, but they usually only address parts of the problem or introduce new ones:

Putting test-objects into their own files This might remove the distraction - but it also removes the property the test is about. Also, it does not help you with the sclaing issue - on the contrary. Creating a file for every test or maybe different test scenarios, you now have to go into every file whenever something on the source type is changed. And it becomes quite a mess pretty fast.
Casting with TypeScript's as
```
  const unfinishedTodo = {
    done: false
  } as Todo;
```
While this most certainly works, it leaves a bit of a bad taste as it is actually cheating the type system, thus openning the door to nasty and hard to track bugs. If the function under test expects a Todo, we should provide a full-fledged object and not just a partial one. Maybe the unit under test relies on a ceratin property not being undefined even though it's not really relevant for the test (thinking of a 'stub'). Plus you have to type as Thing everywhere which again is quite a bit of a distraction in my eyes.
Spreading on a default object
```
  // In a separe file or on top of your test file...
  const defaultTodo: Todo = {
    title: 'Default Todo Title',
    done: false,
    dueDate: new Date('2021-07-04'),
    assignee: 'David Losert',
    project: 'Writing Blogposts',
    tags: ['writing', 'blogs']
  }

  it('markTodoAsDone sets done to true.', () => {
    const unfinishedTodo: Todo = {
      ...defaultTodo,
      done: false
    };
    // ...
  }
```
This heads into a better direction. The test remains focused on the relevant properties, yet our unit under test always gets a real Todo-object as opposed to when casting. It also scales somewhat: changes to the type only have to be applied to the defaultTodo-object. And we get another bonus: the defaultTodo serves as a great documentation on how a real Todo-object might look in production.

There remains a tiny problem with this approach: Your tests are now tightly coupled to the defaultTodo-object, which might again introduce problems with - you might have guessed it - scaling. And I wouldn't write this if I did not know of a slightly better approach.

Enter the stage: TypeScripts `Partial` and a factory-function

So the way I usually go is a combination of TypeScript's Partial and a simple factory function. I'll show you the code before going into the details.

createMockTodo.ts:

const defaultTodo: Todo = {
  title: 'Default Todo Title',
  done: false,
  dueDate: new Date('2021-07-04'),
  assignee: 'David Losert',
  project: 'Writing Blogposts',
  tags: ['writing', 'blogs']
}

const createMockTodo = (overwrites: Partial<Todo> = {}) => ({
  ...defaultTodo,
  ...overwrites
});

export {
  createMockTodo
};

The usage of might look like this:

todo.test.ts:

it('markTodoAsDone sets done to true.', () => {
  const unfinishedTodo: Todo = createMockTodo({ done: false });

  const resultingTodo = markTodoAsDone(unfinishedTodo);

  assert.deepStrictEqual(resultingTodo.done, true);
}

So there is a few things happening here, let me walk you through the most important ones:

defaultTodo is basically the same as in the section before: A fully defined object of the type to make it easy to always get all (required) properties from a single place. Additional advantage: It serves as documentation about the type.
But rather than exporting this object directly, we use a factory function createMockTodo. This gives us way more control over how the actual mock-object is constructed. You will see how this helps us further down.
Partial<T> is a TypeScript utility type that accepts another Type or Interface as generic argument (if you don't know about generics, I recommend you read the official docs). It then creates a new type by copying all properties of the given generic input type but with all properties set to optional.

This lets us pass in a object with only the properties of our choosing (as we did with done in the example) while at the same time keeping type-safety turned on. We can only pass things that actually exist in Todo.
We use an empty object as deafult argument to overwrites so that we can also call the factory-function without any parameters. This is especially useful if you just need some stubs in your test but don't care about the precise properties.
We then finally construct the test-object by merging together all properties of defaultTodo with the overwrite object using the spread-operators.

Like this, all properties given to the function will overwrite the ones in defaultTodo (as the name indicates) while leaving the other properties in place.

Advantages of this pattern

It scales: when adding new properties to the original type, you only have to adjust the default-Object in a single place
It scales again: If for any reason you need to construct the mock-data differently (e.g. because of deeply nested structures, see below), you are completely free to do so within the factory-function without having to change any callers.
Type-safety is on at all times. This prevents you from introdcuing nasty bugs, as well as making refactorings easy, especially with IDEs that support things like renamings (Hit F2 in VSCode ;) ).
It's immutable: As long as you don't have nested objects (again, see below on how to handle those), you are guaranteed to get a new copy for every test, preventing another sort of nasty bugs where tests might influence each other.
It's documentation: You can give the default-object meaningful values to have a documentation on how it might look like in production.
It's reusable: This pattern can be used in a lot of different scenarios - it is actually not even limited to data-objects as you might find out if you read on.

Extending the pattern

The pattern as shown is already useful in a lot of ways. But I promised you scaling, so let me show you how to further extend it for more special use-cases.

Use mock-factories in other mock-factories

Lets say we introduce a User-Type in our App that might look like this:

User.ts

type User = {
  id: string;
  firstName: string;
  lastName: string;
  pronouns: string;
}

We then create a mock-factory for it:

createMockUser.ts

const defaultUser: User = {
  id: '29f51e42-c6ca-4f17-ac93-7131eeb4cffc',
  firstName: 'Kim',
  lastName: 'Su',
  pronouns: 'they/them',
}

const createMockUser = (overwrites: Partial<User> = {}) => ({
  ...defaultUser,
  ...overwrites
});

Now we want to adjust our Todo.assignee-Property to use this type rather than a string:

Todo.ts

type Todo = {
  title: string;
  done: boolean;
  assignee: User;
  dueDate: Date;
  project: string;
  tags: string[];
}

This will break all our tests at first, so we quickly adjust the default-object in the Todo-Factory:

createMockTodo.ts

import { createMockUser } from './createMockUser';

const defaultTodo: Todo = {
  title: 'Default Todo Title',
  done: false,
  assignee: createMockUser(),
  dueDate: new Date('2021-07-04'),
  project: 'Writing Blogposts',
  tags: ['writing', 'blogs']
}

const createMockTodo = (overwrites: Partial<Todo> = {}) => ({
  ...defaultTodo,
  ...overwrites
});

export {
  createMockTodo
};

And that's it. Our tests should work again, given they did not involve or overwrite the user object. And if they did, we can now easily find them through our typechecks (or by following the failed tests for that matter).

For example imagine we had a test like this before the change:

Todo.test.ts

it('changes the assignee to the new given user.', () => {
  const givenTodo = createMockTodo({
    assignee: 'David Losert'
  });

  const { assignee: actualUser } = assignTodo(givenTodo, 'Rahim Vera');

  assert.deepStrictEqual(actualUser, 'Rahim Vera');
});

Now we could write it like this:

it('changes the assignee to the new given user.', () => {
  const givenTodo = createMockTodo({
    assignee: createMockUser({ id: 'oldId' })
  });
  const expectedUser = createMockUser({ id: 'newId' });

  const { assignee: actualUser } = assignTodo(givenTodo, expectedUser);

  assert.deepStrictEqual(actualUser, expectedUser);
});

We have to be careful though: Now that we use nested objects, we are actually able to mutate the values within the defaultTodo:

const myFirstTodo = createMockTodo();
console.log(myFirstTodo.assignee.firstName); 
// Logs 'Kim'

myFirstTodo.assignee.firstName = 'MutatedName';
const mySecondTodo = createMockTodo();
console.log(mySecondTodo.assignee.firstName); 
// Now Logs 'MutatedName'

This is due to the fact that the spread-operator only does a shallow copy of an object, but passes deep nested objects by reference.

This is not too bad if we are actually certain that we are using immutabilty throughout our app. But if not, there is the option of deep cloning.

Use `cloneDeep`

As there actually is no standard way of deep cloning an object in JavaScript / TypeScript, we'll either have to implement it ourselfs or use a library that does it for us. For the simplicity of this post, I will be using the cloneDeep-function provided by lodash, since it is probably the most popular one.

If we do not want the full lodash-library in our project, we can also do a standalone install of the cloneDeep function and mark it as a dev-dependency (so long as we only use it in our tests):

npm install --save-dev lodash.clonedeep @types/lodash.clonedeep

Please note that you will have to add "esModuleInterop": true in the compilerOptions-section of your tsconfig.json to be able use it.

Now all that is left todo (pun intended) is to adjust the mock-factory accordingly:

createMockTodo.ts

import cloneDeep from 'lodash.clonedeep';

// ...

const createMockTodo = (overwrites: Partial<Todo> = {}) => {
  return cloneDeep({
    ...defaultTodo,
    ...overwrites
  });
};

And that's it. Now you have a truly immutable mock-factory. Note how we did not have to adjust any tests or other areas of the code to make this central change.

Sum up

As shown, the mock-factory-pattern is a big win in scalibility and focus for creating test-data while at the same time being pretty simple. The simplicity makes it reusable for almost every object, and I even use it sometimes to mock IO-Modules like HTTP-Services.

Using the same pattern for all test-data makes writing tests more approchable, and it is especially helpful for newcomers to the project as they can see default implementations of all the relevant data and types.

By having a mix of a default-object and a factory-function, it becomes super flexible while at the same time minimizing maintenance tasks and the need for more static mock code. To put this into perspective: I once was able to delete ten thousands of lines of code from a project simply by introducing this pattern.

And there are still a lot of other ways to use and extend it, but I'll leave it up to you to find and use them.

Link to working example

You can find a working example of the code in my Github repository:

davelosert / mock-factory-pattern

This repository shows the mock-factory-pattern and accompanies my blog-post about it.

Mock-Factory-Pattern in TypeScript

This repository shows a mock-factory-pattern-example in typescript.

The mock-factory-pattern uses a combination of TypeScript's Partial together with a factory function to be able to create scalabe, reusable and focused test data:

const defaultObject: ExampleType = {
  key1: 'value1',
  key2: 'value2'
  // ...
};

const createMockObject = (overwrites: Partial<ExampleType> = {}) => ({
  ...defaultObject,
  ...overwrites
});

export {
  createMockObject
};

You can find two implementations of this pattern here:

src/createMockUser.ts: simple example
src/createMockTodo.ts: example using cloneDeep to ensure immutability.

You can read more about it in my blog-post which this repository accompanies.

Setup

To execute the tests:

Clone this repository and cd into it on your terminal
npm install
npm test

View on GitHub

Practical guide to use the Microsoft Graph-API

David Losert — Tue, 06 Apr 2021 15:38:45 +0000

The Microsoft Graph-API is the gateway to almost all data living within a Microsoft365 subscription, and is therefore a super powerful API for a lot of different use cases.

But approaching and using it for the first time can be very difficult and overwhelming – especially because the official documentation is very complex and information is shattered across a lot of different pages.

I just had to create a serverless function in Node.js that retrieves some data from a SharePoint-List – and while trying to find out how to do that, I got lost clicking from page to page, concept to concept and code example to code example to find a quick and easy solution I can built upon.

The goal of this post: A pracitcal guide

The main problem I had was: How to correctly authenticate and authorize my backend-app with a simple secret to use the Graph-API to query general (non-user related) data?

With this post I want to save you the trouble I went through and show you exactly this in a practical guide. I will only explain enough theory for you to understand what is going on.

The guide explains how to set everything up to query the SharePoint root site as an example, but it also explains how to adjust everything to match your desired data.

The code examples are written in TypeScript and run in Node.js. But as we will be using the official Azure auth library @azure/msal-node which is available in other languages as well (you can find a list here), the concepts should still be applicable if you fancy another language.

I am also planning to write a second part to this post that takes a deeper dive into the concepts behind the authentication and authorization models of Microsoft365 and that will explain some leftover questions from this first part – so stay tuned.

But for now, let's get started.

Prerequisites – What you need to know first

Azure AD Application required

In order to authenticate with the Graph-API, you must register an app in the Azure Active Directory (Azure AD for short). This is the way of creating a technical user for the API, and there really is no way around this.

In hindsight, this was one of the changes in my mental model I had to go through to understand the auth-mechanism of Microsoft365: Rather than creating a (somewhat anonymous) technical user to use the API, you actually register the app itself as identity within your account.

For the use-case of this post, there is no real technical difference between the two. However, Microsoft allows for far more complex authentication scenarios where this becomes very relevant. I'll talk about those in the second part.

Administrator Privileges required

You will need administrator privileges to register the app. If you don't have them, there are three other options:

You ask your IT-Department or whoever is in charge to register the app for you.
You use the App registrations page in Azure if you have access. This is the admin-free version of registering an app and you can then follow all of the steps below – however, you won't be able to give the consent required in step 1.3. and then still need an administrator to consent for you.
You create a completely free Microsoft365 Developer test account here – which gives you a full Microsoft365 E5 Subscription for a renewable 90 days. This is perfect as a playground and what I did to test the code of this post.

Practical Guide

Now lets dive into the practical part which consists of three parts:

1. Registering an Azure AD Application
2. Using TypeScript to query the API
3. Using the Graph-Explorer to find the right query

1. Registering an Azure AD Application

If you have administrator privileges, you can reach the Azure AD App registrations page by opening your browser and navigating to https://aad.portal.azure.com. This should bring you to the Azure Active Directory admin center of your Microsoft365 or Azure Subscription once you logged in with your administrator account.

Alternatively, you can reach it from either within your Microsoft365 admin center in the navigation on the left, or from the Azure portal by searching for it in the top bar.

Whatever way you chose, once you are there, on the left side click Azure Active Directory and then App registrations.

Next, we'll have to do 3 things: register the app, then create a client secret and in the end add some permissions to it – which I'll explain step by step.

Don't worry of making any mistakes here – you can always adjust the settings later and there is absolutely no risk of creating any costs as registering an app is completely free.

1.1. Registering the Application

Click New Registration on the top bar.
Fill the Form with a name of your choosing and select "Accounts in this organizational directory only" (you can omit the Redirect URI), then hit Register.

You should see a summary screen of your app from which you will later need the values of the Application (client) id and the Directory (tenant) id. You can copy and store them now or retrieve them again later.

Think of those variables like this:

tenant-id: The unique Id of the entire Microsoft365- or Azure-Account.
client-id: The username of the technical user our application will use to authenticate.

Now all that is missing for a proper authentication is a password or client-secret – we will create this in the next step.

1.2. Authentication: Create a client-secret

On the left, select Certificates & secrets and click New Client secret.
Give it any name and choose an expiry date (you can just use Never for now).
You should see the created secret and the value in clear text. Copy and store this value somewhere now – this will be the only time you can see it.

One note: Don't confuse the ID field of this screen with the client-id of the previous step – they are not the same and you won't need the client-secret-id from here anymore.

Now we have everything we need to let our application authenticate against Azure AD. However, we didn't tell Azure-AD what data our application is allowed or authorized to retrieve yet, so lets do this next.

1.3. Authorization: Grant permissions to your app

Still on the Azure AD Application page:

Select API Permissions and hit Add Permissions.
Select Graph API.
Select Application permissions.
Search and select Sites.ReadAll. This is the permission that allows us to read all SharePoint-Data. If you need to query other data and therefore need other permissions, you can later use the Graph-Explorer as explained in Step 3.
Click Add Permissions.
Back on the permissions-screen, click Grant admin consent to actually allow those permissions. I'll explain in the second part why this is necessary, for now just do it.

And that's it. Now we are ready to write some code to use the Graph-API and retrieve SharePoint-Data from our Microsoft365 account.

2. Using TypeScript to query the API

2.1. Install the necessary libraries



$ npm install @azure/msal-node node-fetch

MSAL stands for Microsoft Authentication Library and
@azure/msal-node is the official library to authenticate with Azure AD from a Node.js Application. It kind of suffers from the same bloated and confusing documentation as the Graph-API, so finding the right classes and functions to use can be very cumbersome. However, we will see in the code below that we really only need a few lines to make it work.

We are also installing node-fetch as the Graph-API is an http-endpoint – but you can use any other http-library you fancy.

If you found the official client @microsoft/microsoft-graph-client on npm – do not use it. At least according to their documentation, it is not compatible with the simple credential-authentication that we are trying to use here.

2.2. Create a file `queryGraphAPI.ts`

Have a look at the full code-example first and explain the details after:



import * as msal from '@azure/msal-node';
import fetch from 'node-fetch';

// 1.
const tenantId = '<YOUR_TENANT_ID>';
const clientId = '<YOUR_APPLICATION_ID>';
// 2.
const clientSecret = '<YOUR_CLIENT_SECRET>';
// const clientSecret = process.env.CLIENT_SECRET


const clientConfig = {
  auth: {
    clientId,
    clientSecret,
    // 3.
    authority: `https://login.microsoftonline.com/${tenantId}`
  }
};

// 4.
const authClient = new msal.ConfidentialClientApplication(clientConfig);

const queryGraphApi = async (path) => {
  // 5.
  const tokens = await authClient.acquireTokenByClientCredential({
    // 6.
    scopes: ['https://graph.microsoft.com/.default']
  });

  const rawResult = await fetch(`https://graph.microsoft.com/v1.0${path}`, {
    headers: {
      // 7.
      'Authorization': `Bearer ${tokens.accessToken}`
    }
  });
  return await rawResult.json();
}

export {
  queryGraphApi
};

How this code works

You will recognize the tenantId, clientId from step 1.1. – fill them in here directly.
The clientSecret from step 1.2. is sensitive information, so you should not be using it in your code and never commit it to your repo. For a quick test it's okay, later on you better provide this value through an environment variable.
The authority is the endpoint that the msal-library will authenticate with. Maybe now it is clear why you need the unique tenantId – it let's the generic login-endpoint of microsoft know for which account your are trying to authenticate.
We are using the ConfidentialClientApplicaton-Class of msal. It is named confidential as our application is running completely in the backend where the clientSecret is safe. There is a differentiation to public clients as the msal library also offers authentication mechanisms for browser-based applications where using a general secret would not be secure (everyone could read and use it).
As you might see, we do not query the Graph-API with our credentials directly, but we only use them to get an access-token. If you are familiar with the OAuth2 and OpenID stack, you might recognize this pattern. If not don't worry, I'll talk more about it in the second part.
With the scope, we tell the auth-endpoint that we want the token to be allowed to access the Graph-API with the .default-permissions – which are the ones we configured already in Step 1.2. For our use-case, this is the only possible option, but again there are other use-cases where setting other values here makes sense (which – you guessed it – will be covered in the second part).
Finally, we query the Graph-API endpoint with the retrieved token. The path Parameter defines which data to query, and in 2.3. we will use it with /sites/root which is the SharePoint Endpoint.

2.3. Use the API in an `index.ts`



import { queryGraphApi } from './queryGraphAPI.ts'
// In case you don't have top level await yet
async function start() {
  const sharePointSite = await queryGraphApi('/sites/root');
  console.log(sharePointSite);
}

start().then(() => console.log('Complete.'));

Now if you start the program you should see a result like this:



$ npx ts-node index.ts
{
  '@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#sites/$entity',
  createdDateTime: '2021-03-13T12:54:48.047Z',
  description: '',
  id: 'davelosert.sharepoint.com,0d19a070-63ba-40f8-872a-f83df5120b2a,770d1b68-3e43-44f2-aab4-ffc0bfe8c6a1',
  lastModifiedDateTime: '2021-04-02T15:21:33Z',
  name: '',
  webUrl: 'https://davelosert.sharepoint.com',
  displayName: 'Communication site',
  root: {},
  siteCollection: { hostname: 'davelosert.sharepoint.com' }
}
Complete.

Of course, this is just really simple code for a first working solution, but it's enough if you just need to query your data once in a while. If you plan to query the api more often, you might consider caching the token rather than requesting it on every query. The msal-library already supports caching
by providing a plugin and you can find an example on the Github Documentation – but covering this is out of scope of this post.

3. Using the Graph-Explorer to find the right query

Okay so now you should be able to query the SharePoint-Root-Site. However, I am pretty sure this is not the data you are after. So where to go from here?

One option is to start looking in the Graph-API reference documentation to get an overview of what is possible.

A more interactive and my recommended approach is using the official Graph-Explorer. This browser-based application lets you play around with and query the Graph-API and get immediate feedback about the responses. This makes it a great tool to find out both, the exact path and query as well as the permissions you need for your use-case.

The Graph-Explorer is mostly self-explanatory, so I won't get into too much detail here. But an approach to find the right query might be:

On the left, select a Sample Query that comes closest to what you are after
Run the query.
You might need to give consent in the tab Modify permissions so the Graph-Explorer is allowed to query the data in your name.

Do you recognize this pattern? This is bascially the same as the admin-consent we gave in 1.3. – but this time for the Graph-Explorer App and rather than in the name of an admin, you give it in the name of **your* account.*
The Modify permissions tab is also a great place to see which permissions are required to query the endpoint. However, it sometimes shows more permissions than you need.

For example for the sample query SharePoint Sites / my organization's default SharePoint Site (which is our query from Step 2), it shows both,
Sites.Read.All and Sites.ReadWrite.All. But as we saw, the former is enough to read and the latter is only required if you also plan to write to SharePoint.

Once you know which permissions you need, you can add them in the App registrations page like we did in Step 1.3.
Refine the Query until the output matches what you are looking for.

One last thing to consider:
As described, the Graph-Explorer runs in the context of your logged-in user, not your application. This means even if you consent here, your App will not automatically get those permissions. As explained in 4., you still have to explicitly add them to your app.

Summary

As you might have seen, getting started with the Graph-API can be quite challenging. Especially the authentication and authorization part are a bit more complex to set up and not very intuitive at first.

But once you know what to do and where to look, it is only some clicks and a few lines of code to make it work. For the serverless-function described in the intro, it took me hours to make it all work. But registering the application and setting up the code examples for this post only took me around 15 minutes.

So hopefully I reached my goal to save you the hours of work and get started with the Graph-API more quickly.

As announced, I will soon publish a second blog-post where I'll go a bit deeper into the theory and concepts behind all of it.

However, if you have any feedback or open questions, feel free to comment below and I'll answer as soon as possible.

Naming workarounds in code

David Losert — Sun, 30 Aug 2020 10:32:52 +0000

Some weeks ago, I gave an advice in a code review to better mark a temporary workaround with a very long and descriptive function name. As I really like that approach, I want to share it with the world in this post.

Why good naming is important

First I want to talk briefly about why I think taking the time to find good names in code is so important.

"Coding" to me usually means more reading or thinking than it means writing. I never measured this, but my feeling is that the ratio is even sometimes up to 95% reading (or thinking) and only 5% actively writing.

This is especially true for bugs: I probably can't count how many times I tried to find the cause for a certain behavior or bug for hours – only then to fix it within a few seconds.

But even in less extreme situations, I usually read way more than I write. And I am going out on a limb here and claim this is true for most coders.

Following this logic we can say: the better readable our code is, the more efficient we will be writing it. And probably also have more fun in doing so. :)

But what is readable code?

Well, the bad news here is: It depends. Readability is really a subjective thing and you'll often find that what one person considers readable completely throws off another.

Yet, I believe that there is a certain base level of practices with which you can achieve a overall better readability for a majority of readers. And that includes good and expressive variable and function names.

Just consider this basic example with non-expressive names:

const convert = (value) => {
   const y = getExchangeRate('Dollar', 'Euro');
   return y * value;
}

Just looking at the function name itself, one might understand that it is converting some value. But to know what it is converting, you have to read on.

Seeing the call to getExchangeRate and the multiplication of the value in the end, you can assume that the function converts money from one currency to another - the currencies being 'Dollar' and 'Euro'.

But in which direction is it converting? Euro to Dollar or Dollar to Euro? Given the order of the arguments passed to getExchangeRate, you might assume it's Dollar to Euros. But if you wanted to be sure about it you'd also have to look inside getExchangeRate. Depdening on it's complexity, that might be a lot of reading.

Now let's make this a bit clearer:

const convertDollarToEuro = (dollar) => {
  const exchangeRate = getExchangeRate('Dollar', 'Euro')
  return dollar * exchangeRate;
}

Like this, all of the assumptions and questions we had before don't even come up. It is already clear that the function is converting dollars to euro just by it's name. Also within the function, the variable names are clearer in what they actually stand for.

Of course this is a basic example - but if you stick to this kind of expressive names throughout your code, you will be able to read and navigate through it way faster.

The case at hand

Now as wirtten in the introduction, I was doing a code review. The code was about mapping some data from an external API into our own object structure.

Note: I simplified the example to focus on the method rather than the project itself So now it is about kittens.

The code I reviewed looked something like this:

const kittenAPIData = await requestKittenFromApi();
const kitten = {
   name: kittenAPIData.name,
   owner: kittenAPIData.owner.fullName,
   furrColor: kittenAPIData.colorOfFurr || '',
   homeTown: kittenAPIData.location.city
   // ... and many more mappings 
}

You might already have stumbled upon Line 5: Why is there a or condition falling back to an empty string for the property furrColor?

My first assumption was that this it is setting a default value for an optional field. But why only for this line and not the others?

As assumptions are evil, I went ahead and asked the developer who wrote it.

As it turned out, this was only a workaround due to a bug in the API: Instead of returning the value for furrColor, it was always returning null. And my assumption of it being optional was wrong as the rest of the code relied on it being set.

The API Developers already knew about this bug and said they were going to fix this soon. So in this case, the workaround was a nice way to let them fix it whenver they want without having to synchronize our deployments. As soon as the API returned the correct values, our code would the right thing automatically.

As much as I like developer communication, it would have been nice to avoid the confusion and extra effort of me asking by being able to see this is a workaround directly in the code.

How to mark a workaround in code

One thing that might come to mind are comments:

const kittenAPIData = await requestKittenFromApi();
const kitten = {
   name: kittenAPIData.name,
   owner: kittenAPIData.owner.fullName,
  // Defaulting to empty string is a workaround due to a bug in the API returning null
   furrColor: kittenAPIData.colorOfFurr || '',
   homeTown: kittenAPIData.location.city
   // ... and many more mappings 
}

This is already better. But well - comments tend to get overlooked. At least I usually read logic first, comments (maybe) later. Also, as this was a bug that would get fixed soon, I wanted the next person stumbling upon this to definitly check and maybe delete the then unecessary workaround.

So why not use an expressive function name to mark it for what it is?

const kittenAPIData = await requestKittenFromApi();
const kitten = {
   name: kittenAPIData.name,
   owner: kittenAPIData.owner.fullName,
   furrColor: defaultToEmptyStringAsTemporaryWorkaroundToBugInAPIReturningNull(kittenAPIData.colorOfFurr),
   homeTown: kittenAPIData.location.city
   // ... and many more mappings 
}

function defaultToEmptyStringAsTemporaryWorkaroundToBugInAPIReturningNull(colorOfFurr) {
  return colorOfFurr || ''
}

Yes, you are seeing this correctly: A 63 character long function name explaining exactly what is going on. Did you get alerted by this? Well good - that was the intention. :)

In my opinion, this approach has several advantages:

It most definitly won't get overlooked by anyone
If I'd stumble upon this, I'd definitly check if the bug still persists and delete the workaround if not
It tells the reader not only what is going, but also why it is there in the first place

Now this approach shouldn't be used too often as it would then defy the purpose of alerting the reader. But I think it's a neat trick sometimes to really strike attention and let others or myself know that the written code here is not supposed to stay in forever.

And as oppsed to just a comment that may even contain a todo, this function name is really painful and gives a lot of motivation to refactor as soon as possible.

Dependency Inversion with Redux-Thunk & Typescript

David Losert — Fri, 03 Jan 2020 10:22:10 +0000

In this article I will explain how we used Dependency Inversion to decouple all I/O modules in our React-Redux-Application resulting in the ability to completely change the Apps behavior by setting a Boolean during bootstrapp time.

I origanally published this blog post on medium two years ago - but as I like my content to be my own, I am republishing it now here ;)

One of my favorite and in my opinion most powerful software principles is the Dependency Inversion Principle — or short DIP. It is the D in the famous SOLID Principles and it drives most patterns I know that take care of decoupling and modularization. Even more: Usage of the DIP actually makes the difference between a real OO-Design and a procedural one according to Robert C. Martin:

Indeed, it is this inversion of dependencies that is the hallmark of good object-oriented design. […]. If [a program’s] dependencies are inverted, it has an OO design. If its dependencies are not inverted, it has a procedural design.

Robert C. Martin — Agile Software Development: Principles, patterns and practices

Now some people might stop and say: But this article is about redux which celebrates functional programming. What do I care about OOP and OO-Design?

In my opinion it doesn’t matter whether you use FP or OOP. Understanding and applying the DIP will help your tremendously in both disciplines, since you will always have to handle dependencies somehow — wether it is a class or a function.

What is Dependency Inversion?

Before we go into the details, I’d like to give a brief introduction to dependency inversion. If you are already familiar with it, you can skip this section.

As the name states, dependency inversion has to do with dependencies of classes / functions — more precisely with the abstraction of those dependencies.

Lets look at an example: We use a classical App-Structure which has some sort of View, a Data Service and an API or Database-Service:

The flow of control is like this: the View reacts to a certain user-interaction by calling a function on the DataService which itself calls a function of the API or Database to request some raw data, applies some domain rules before or after the call and then returns the data to the view.

What we can see on the Diagram really well is that the dependency-chain exactly follows this control-flow — the View depends on the DataService which itself depends on the API.

This is a problem though: As the DataService is part of our Domain and thus contains the fundamental rules of our application, it should not depend on anything else but other parts of the domain layer so that it stays testable, isolated an free of unecessary changes. After all, we expect the least changes to our domain and we want it to be the most stable part of our application, right?

With this current way of implementation however, if the API changes only a bit, most likely the domain has to change as well. And since the view depends on the Domain, this will most likely have to change as well — meaning we’d have to touch several or all parts of our application if only one minor detail on one of the outer layers of our application changes. This kind of cascading changes are a lot of work that is actually not really necessary.

Now lets see what can be done using an interface and thus applying DIP:

By simply putting the interface DataRepository between the domain service and the API, we already achieved a decoupled architecture. What is important here: The domain service owns that interface (or: the interface is part of our domain) while the API only implements it from the outside.

That means the domain now only depends on itself (this is what we wanted) and only specifies what it needs from the outside world — but not how it needs it. The DataService can work with anything that implements the DataRepository-Interface — let it be a real database, a HTTP-API or simply an In-Memory-Repository with mock data. All that needs to be done is inject the right dependency during the bootstrapping phase of our app.

Further: What we achieved now is that the ApiService actually depends on the domain rather than the domain depending on the API. That means the direction of the dependencies is inverse to the flow of control (red vs. black arrows) — hence the word Dependency Inversion.

How is this done with Redux-Thunks?

Now let’s transfer this to the classical react-redux application: There are some containers+components (the view) which dispatches actions (the domain) to redux to change the state. Some of those actions are asynchronous as they need to get certain data from an asynchronous API. A simple way of doing that is by using the redux-thunk middleware. Therefore, a simple app architecture could look like this:

The implementing code might look like this (of course, it is one of our beloved Todo Apps):

As in the abstract example before, the container (view) directly depends on the redux-thunk action (domain) which itself directly depends on the fetch-method (the API).

The same problems from the abstract example arise now more clearly:

The direct coupling lets the rather stable domain-code (the thunk) depend on the usually rather unstable API. Whenever the API changes just a little bit (a path changes), we will have to touch the thunk and it’s tests as well.
By directly coupling the action to the API, testing this thunk is very hard (right now you would have to somehow mock the global fetch method)
While developing, we don’t always have the luxury of an already existing or stable API and prefer to work with Mock-Data — our only chance to do so with this approach is to start some sort of JSON-Mock-Server that actually answers the HTTP-request on the correct URL.

So here we also want to use dependency inversion to abstract the API behind an interface and let the thunk only depend on that interface.

Lets clean it up

For the gists in this example I pulled out the most important code snippets. You can find a full working implementation of the example in my Github Repository:

davelosert / di-with-redux

Example how to do dependency inversion with redux - used for a blog post

The target structure should look something like this:

So first, lets pull out a TodoRepository Interface and create an APIService named HttpTodoRepository implementing it. Note how this simple refactoring already separates the role (being a repository for data) from the implementation and the used technology (use HTTP to fetch the data):

Now we need to somehow pass in the HttpTodoService as TodoRepository to the thunk. We could do this by adding it to the parameters-list of the thunk itself — but that would mean all containers dispatching the action have to know about the service, and that is simply not their task (think Single Responsibility Pattern).

Luckily, redux-thunk allows us to specify a third parameter during bootstrap which will be passed to every called thunk. We can simply use that parameter as a dependency-injection mechanism:

And now we can use it in the thunk itself like so:

The TodoRepository is now the third parameter to the thunk-function. Further, the thunk-action knows nothing about the concrete implementation in HttpTodoRepository anymore. We successfully decoupled the domain from the API.

To see the real power of this abstraction, lets now also write a MockTodoRepository implementing our TodoRepository interface:

All that is left to do now is pass the MockTodoRepository instead of the HttpTodoRepository when our store is created and the app suddenly works completely independent of internet connections and without a running API.

This can be further improved by using a environment variable which will be passed from the outside to decide which of the two Repository-Implementation will be used:

The setting of this variable can be completely dynamic. We usually do it by using Webpack’s DefinePlugin where we set MOCK_API to either true or false depending on a given parameter at build time. This way, we can start our app in either mode from the CLI (npm start vs. npm start:mock)

With one simple variable, we can now completely change our apps data-behavior while not changing its logical behavior at all. With this architecture, changing your API from REST to GraphQL or from HTTP to HTTP2 is nothing more than writing a new service implementing the DataRepository Interface.

But how does this scale?

We are actually using this architecture in a bigger application and made some very good experiences with it. To be able to scale, we are actually not injecting the APIService itself, but (also environment specific) Factory holding all our dependencies. That way, every thunk has the possibility to request whatever dependency it needs instead of just the API.

When our API wasn’t available for two weeks, we still could develop our frontend app easily and even let our POs test it logically by faking backend behavior with an In-memory API (so Create/Update/Delete operations where possible).

Summary

you can use redux-thunk’s thunk.withExtraArgument(deps) function as a dependency injection mechanism
to avoid tight coupling, let your thunk (or your domain) specify the dependencies it needs as interfaces, not as already concrete implementations
implement those interfaces elsewhere and pass them into the thunks with the function above during bootstrapping
use environment variables (e.g. set by Webpacks DefinePlugin) to decide which implementation of your domain-interfaces you pass into the app to control your apps behavior on the highest level

DEV Community: David Losert

Mock-Factory-Pattern in TypeScript

The initial simple way

Alternative ways

Enter the stage: TypeScripts Partial and a factory-function

Advantages of this pattern

Extending the pattern

Use mock-factories in other mock-factories

Use cloneDeep

Sum up

Link to working example

davelosert / mock-factory-pattern

This repository shows the mock-factory-pattern and accompanies my blog-post about it.

Mock-Factory-Pattern in TypeScript

Setup

Practical guide to use the Microsoft Graph-API

The goal of this post: A pracitcal guide

Prerequisites – What you need to know first

Azure AD Application required

Administrator Privileges required

Practical Guide

1. Registering an Azure AD Application

1.1. Registering the Application

1.2. Authentication: Create a client-secret

1.3. Authorization: Grant permissions to your app

2. Using TypeScript to query the API

2.1. Install the necessary libraries

2.2. Create a file queryGraphAPI.ts

How this code works

2.3. Use the API in an index.ts

3. Using the Graph-Explorer to find the right query

Summary

Naming workarounds in code

Why good naming is important

But what is readable code?

The case at hand

How to mark a workaround in code

Dependency Inversion with Redux-Thunk & Typescript

What is Dependency Inversion?

How is this done with Redux-Thunks?

Lets clean it up

davelosert / di-with-redux

Example how to do dependency inversion with redux - used for a blog post

But how does this scale?

Summary

Enter the stage: TypeScripts `Partial` and a factory-function

Use `cloneDeep`

2.2. Create a file `queryGraphAPI.ts`

2.3. Use the API in an `index.ts`