DEV Community: Kamran Ayub

Hacktoberfest: Can I ask a question?

Kamran Ayub — Thu, 08 Oct 2020 13:22:15 +0000

I have a friend who is doing their first open source contribution through Hacktoberfest this year, which is a yearly event to encourage open source participation.

In their email, they asked:

Is there any etiquette or expectation for how much coding help one can ask for when taking up an issue and contributing?

What a good question! Imagine yourself feeling pretty psyched to take on a Hacktoberfest issue and when you start to dig in to understand the codebase, you start to feel intimidated.

Is it OK to ask for help? Would that be rude to the maintainers?

The short answers are YES and NO (hopefully). Here is my longer answer!

Hacktoberfest projects expect newcomers

There was a little bit of drama this year because historically projects did not necessarily opt into Hacktoberfest and were being spammed with low-effort PRs (or outright useless PRs). However, the rules have changed and now repositories can opt-in in several ways:

They can have a hacktoberfest topic in their GitHub project, like this:

Or, maintainers can mark accepted PRs with the hacktoberfest-accepted, like this:

If one of these is true, the project is considered opted-in to Hacktoberfest.

My expectation as a contributor would be that if a project opted into Hacktoberfest, especially with the topic approach, they are expecting to help you with making quality contributions.

Now since we at Excalibur have always opted-in each year, I can tell you that we expect people to ask questions! We try to triage and choose potential Hacktoberfest issues ahead of time (heh, in "Preptember") but we know that people will likely have questions.

After all, first-time contributors can't be expected to have answers to everything, of course you will need some help along the way. This is especially true for anything beyond mere typos.

But will my question be welcomed?

Now this is getting at a different issue, unrelated to Hacktoberfest specifically and more related to toxicity in the open source world. And let's be real: open source can be toxic.

Here's what I recommend to help avoid a toxic project until it's too late: "scout" a potential project beforehand. Does it have a Code of Conduct? Do the maintainers seem to follow it? How do they react to external contributors asking questions? Are they helpful? How do they review their own code?

Doing some prep work on your part beforehand I think will help having to ask this question in the first place.

Where should I ask?

Start with the CONTRIBUTING document of the project or the CODE_OF_CONDUCT document. An actively maintained project that works with external contributors will typically lay out the expectations for issues and pull requests and may tell you where the best place to get help is. With the recent introduction of GitHub Discussions, that may also be the first place to look if the project is opted-into the beta.

GitHub Discussions is slowly being made available on a opt-in basis

If there's no clear place to start, I recommend first asking within issues, assuming there's a Hacktoberfest issue you're taking. This is also where you'd volunteer to take the issue (like, "🙋‍♂️ Hey, I'd love to try and take this on!").

At that point, maintainers should see your interest and expect that you'll have questions as you get farther into it. If you have questions right away, like about the design, proposal, or a general question, the issue is where I'd ask.

If you have a draft pull request (and I always recommend starting with a draft!) then that is where I'd start asking questions about the approach, feedback on your current solution, etc. A draft pull request is like your writing drafts -- do you send them to your friends to read or an editor? Of course! So get feedback early in the process.

Time to explore the cave, don't go it alone!

I like to think of exploring a codebase like exploring a cave system (or "spelunking" if you're a fancypants). You reveal one area, then reveal the next and that might have any number of offshoot paths or trails back to previous areas, etc. You can get lost in a codebase just as you would a cave system.

Photo by Joshua Sortino on Unsplash

A maintainer is the cave guide. Or maybe just someone who's really been in and out of the cave a ton. Or maybe really, really likes this one area of the cave and knows it blindfolded. The metaphor sort of falls apart because who made the cave, anyway? Nevermind. 🤫

When you ask questions while you are working on a codebase (of any size), it's like you are wandering into the cave and then asking for the maintainer to fill in parts of the cave map, throw you some new flashlight batteries, and tell you, "This is the safe path through. Avoid this one, though!"

Being a newcomer though brings fresh perspective. You might find parts of the cave no one has been through in awhile that could use some dusting. Maybe there's a new pathway the cave has opened up that could be faster than an existing pathway that's well-trodden. You get the picture -- when you ask questions, you may inspire new and better solutions to existing problems maintainers haven't considered.

It's definitely fun to explore a cave on your own at first but it won't be long until your flashlight dies. Ask for help and recharge those batteries! It results in a more agreeable outcome for everyone. Huzzah.

What to avoid

I can't speak for all maintainers but I think it's safe to say that generally maintainers welcome quality contributions (of any kind!).

When you don't ask questions you may end up going down a road that could lead to maintainbility or design issues you haven't foreseen. Remember: this might be your first (and only) time in the cave, it's better to go in prepared!

Always Be Asking

I'd be surprised if you didn't have a question about a new codebase. Actually, it would be unbelievable. Of course you will.

I get it, though. You might be listening to that voice in your head, "You can't ask a question like this, it's a silly question, I will look like a fool, and what will they think of me?" Don't listen!

Listen, it is not a sign of weakness to ask questions, it is how we learn. Doesn't matter if you're brand new to open source, new in your role, or a Principal Engineer -- we ask questions to understand better so Always Be Asking. If anyone (person, company, etc.) expresses to you that asking a question is some sign of weakness, run the other way.

If this is your first time contributing to open source, first, how exciting! Second, I lay out everything I just mentioned in more detail in my course on Contributing to an Open Source Project on GitHub. It's an A-to-Z guide geared toward new open source contributors with practical scenarios, workflows, and a guided process on choosing the right project for you to work on.

Controlling Browser Permissions in Cypress End-to-End Tests

Kamran Ayub — Fri, 17 Jul 2020 02:33:59 +0000

I am excited to release a new open source package cypress-browser-permissions. 🎉

kamranayub / cypress-browser-permissions

A Cypress plugin to set launched browser preferences including permissions like Geolocation, Notifications, Microphone, etc.

cypress-browser-permissions

A Cypress plugin to manage browser launch permissions for various APIs such as Notifications, Geolocation, Cookies, Images, and more.

These APIs can be controlled using browser profile preferences which this plugin will generate and pass for you, as well as resetting them for each test run (otherwise they will be persisted).

This enables you to effectively test permissions-based APIs in continuous integration environments and in headed browsers without prompts. 🎉

Usage

👋 Read the dev.to introduction post for a quick start guide and an example!

Install the

…

View on GitHub

This package solves a real need when testing more sophisticated applications when using Cypress, the end-to-end testing framework. It helps control the permission level of various browser features such as:

Desktop Notifications
Geolocation
Images
Camera
Microphone
etc.

How to Use It

To get started, you'll need to install the package and you'll need Cypress installed already.

npm i cypress cypress-browser-permissions --save-dev

If this is your first time installing Cypress, you'll need to run it once to generate a project structure:

npx cypress open

Then, you need to initialize the plugin to hook it into Cypress' plugin pipeline. In cypress/plugins/index.js, modify it as follows:

+ const { cypressBrowserPermissionsPlugin } = require('cypress-browser-permissions')

/**
 * @type {Cypress.PluginConfig}
 */
module.exports = (on, config) => {
  // `on` is used to hook into various events Cypress emits
  // `config` is the resolved Cypress config
+ config = cypressBrowserPermissionsPlugin(on, config);
+ return config;
};

Now you will have the ability to control various permissions for Chrome, Edge, and Firefox using Cypress environment variables.

For example, if you want to just set permissions for your project you can do so in cypress.json:

{
  "env": {
    "browserPermissions": {
      "notifications": "allow",
      "geolocation": "allow"
    }
  }
}

The plugin will read the permission settings and apply them when launching the browser. It will also reset between launches since modifying the browser profile is persisted across sessions.

You can read more about supported permissions and values in the README.

Writing an End-to-End Notification Test

So let's try it out! Once I finish my Testing Progressive Web Apps Pluralsight course, it will come with an open source sample app. In the meantime, we can write a basic test to see if permissions are working. This same test is included in the repo.

First, we have an HTML file that uses window.Notification to display a desktop notification:

cypress/html/notification.html

<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Cypress Notification Test</title>
</head>
<body>
    <script type="text/javascript">
        const n = new window.Notification('test', { body: 'This is a test!' })
        n.addEventListener('show', (e) => {
            window.__CypressNotificationShown = e;
        })
    </script>
</body>
</html>

You can learn more about how the Notification API works but what we are doing is immediately triggering a notification. Once the browser shows the toast, it triggers the show event on the Notification instance. Since Cypress is awesome and we can hook directly into the window object, we set a callback value globally that we can then inspect/wait for in our test.

If you have a blank Cypress project you do not even need a server as Cypress will automatically host the root of the project when there is no other configuration.

Save the notification.html file under cypress/html and then we can visit that page in the test.

We can create a test suite in cypress/integration:

cypress/integration/notification.test.js

import { isPermissionAllowed } from 'cypress-browser-permissions';

describe("notifications", () => {
    it("should be enabled", () => {
        expect(isPermissionAllowed("notifications")).to.be.true;
    })

    // Only test notification showing in "headed" browsers, which also
    // works in CI :tada:
    Cypress.browser.isHeaded && it("should display desktop notification", () => {

        // Visit the page we created previously
        cy.visit('/cypress/html/notification.html')

        // Wait for the window callback to populate with the event data
        cy.window().its('__CypressNotificationShown').should('exist');
    })
})

Now we can run our tests:

npx cypress open

That's all! If browserPermissions.notifications is set to allow then our test should pass:

And a notification will be shown!

How It Works

In Cypress, you have control over the launch preferences for browsers, so the magic lies in what preferences to pass to each browser.

This topic is not heavily documented as evidenced by this open issue in the Cypress repo I came across while researching this. It has been open since 2018 with no one mentioning the ability to control launch preferences.

Thanks to BrowserStack for documenting some of these permissions as well as these StackOverflow posts:

Selenium + Python Allow Firefox Notifications

Mar 30 '19 Comments: Answers: 1

there is such a question how to implement so that Selenium resolves in that case notifications like this photo https://prod-cdn.sumo.mozilla.net/uploads/gallery/images/2017-10-18-05-45-38-20e1d7.png

it is desirable that he press himself I will be very grateful

Open Full Question

How to allow or deny notification geo-location microphone camera pop up

Dec 28 '17 Comments: 5 Answers: 2

I'm not able to click on Allow button of access camera authentication pop up.

Here is the look of pop up.

Open Full Question

I was able to piece together the information needed to tackle this with a Cypress plugin. Since each browser family uses different preferences, I thought it would be best to abstract it.

What's Next?

My hope is that this package is actually short-lived and the Cypress team can incorporate these permission settings into the core of the product, since it's such an important feature especially when testing new, modern APIs.

There will be a full sample of using Cypress with this plugin (as well as other black magicks such as bypassing service workers and more!) in my Testing Progressive Web Apps course soon on Pluralsight. It should be released in August, you can follow me there to get notified when it releases. The sample app will be open source on GitHub so you'll be able to reference it 👍

Storyflow: Using Storybook to Build a Better... Game Engine?

Kamran Ayub — Tue, 26 May 2020 14:08:00 +0000

Do you use Storybook? Do you use it to test game engines? Didn't think so! But we do for Excalibur.js and I presented how and why we did it. The genesis for the talk came from a workflow I've been using recently that you can implement in your own projects which I call "Storyflow."

Watch the talk

I gave this talk at MN Dev Con on May 4 and again at React Minneapolis on May 21:

What is Storyflow?

The Storybook workflow (ahem, Storyflow) we follow puts Storybook stories at the center of our workflow. The concept is simple in practice: write your unit and functional tests against Storybook instead of importing directly from component files like other workflows.

The "normal" component-based workflow goes like:

Write my component in MyComponent.js
Write my unit test, MyComponent.test.js and import MyComponent
Write a functional test, against my running app, which may test one aspect of MyComponent in use or maybe a few different behaviors/states

But with Storybook the workflow instead flips the script and centers your testing on isolated components through stories:

Write my component in MyComponent.js
Write my Storybook story DefaultState in MyComponent.stories.js and import MyComponent
Write my unit test, MyComponent.test.js and import DefaultState from stories
Write a functional test against DefaultState story in Storybook

It's comes down to a slight shift in thinking. Without Storybook, normally you'd be putting your component into different states within your unit tests. With Storybook, you're already showcasing your component in different states, which makes your unit tests a lot trimmer. Finally, you can add UI testing on top of it to ensure your component works in the browser (without having to manually verify in Storybook).

There are 3 major benefits we've seen from this:

One source of truth for all our tests (stories)
Incentivizes writing more stories
Promotes more testability

One source of truth

Since your unit and functional tests are run against stories, Storybook becomes the source of truth for any tests. Contrast that to developing without stories, where each test could render components in different states and the only way to know would be to examine each test. Having a published Storybook as a static site makes things a lot more discoverable.

Incentivizes writing more stories

Since tests are written against stories, in order to write more tests... you'll need to write more stories. Having more stories means better documentation (even if it's just code!).

Promotes more testability

In order to write a solid Storybook story, it has to run in isolation. That means that you will likely lift up more heavy concerns like data fetching, state management, and other stuff higher and have more atomic reusable components. We actually still write stories against our "container" components but it requires a lot more mocking using Storybook decorators.

Example

If you're curious to see this in action, I have a GitHub Repository set up you can clone and run and I showcase this workflow within the video above.

kamranayub / example-storyflow

Created with CodeSandbox

Storyflow Example

Companion demo to my talk, Using Storybook to Build a Better... Game Engine?

Showcases using Storybook as the basis for unit and functional tests aka "Storyflow" workflow. Uses Storybook, Jest, and Cypress.

Getting Started

Prerequisites

Yarn 1.x (or replace yarn with npm)
Node 12.x

# Install dependencies
yarn

# Start Storybook
yarn start

# Run Jest tests
yarn test

# Run Cypress test runner
yarn cypress open

# Run Cypress tests headless
yarn cypress run

View on GitHub

You can view a working demo on CodeSandbox using the repository!

Does this sound interesting to you? If you're using Storybook, are you writing tests against it or not right now?

Originally posted on my blog, Kamranicus.com

Why You Don't Need Types in JSDoc when Documenting TypeScript

Kamran Ayub — Wed, 05 Feb 2020 16:53:27 +0000

I work with many folks who are coming from native JavaScript and learning TypeScript and I've noticed one small thing during code reviews that can save some time. Here's a quick tip if you're used to writing "regular" JSDoc!

One huge benefit of using TypeScript and documenting with JSDoc syntax is that you can avoid having to specify JSDoc types in your docs! If you want to read the full specification check out Microsoft's standard, tsdoc.

Here's an example of a native JavaScript function with JSDocs:



/**
 * Clamps a `value` between a `min` and `max` inclusive
 *
 * @param {Number} value The value to clamp between `min` and `max`
 * @param {Number} min The minimum number of the range
 * @param {Number} max The maximum number of the range
 *
 * @returns {Number} The clamped value
 */
export function clamp(value, min, max) {
  return Math.min(Math.max(min, value), max);
}

In TypeScript, you're already statically typing your arguments and return type so there's no need to repeat them in the JSDoc. Lose 'em!



/**
 * Clamps a `value` between a `min` and `max` inclusive
 *
 * @param value The value to clamp between `min` and `max`
 * @param min The minimum number of the range
 * @param max The maximum number of the range
 *
 * @returns The clamped value
 */
export function clamp(value: number, min: number, max: number) {
  return Math.min(Math.max(min, value), max);
}

Bonuses:

A refactor-rename (F2 in Visual Studio Code) of a param will sync the JSDoc param names for you
VS Code has autocomplete suggestions for parameter names as you type your JSDocs
VS Code and many other tools support Markdown in JSDoc

Here's what you'll see in your editor now:

View in TypeScript playground

Using Storybook in a Monorepo

Kamran Ayub — Tue, 17 Sep 2019 12:41:22 +0000

I'm currently working in a small monorepo and we have multiple packages set up for shared components, like this:

packages/
  atoms/
  molecules/
  organisms/

Each package has React components under a src directory and since each directory is a package, they also contain node_modules (more on why that's important below).

packages/
  atoms/
    node_modules/
    src/
      components/
        Hello.js
        Hello.stories.js
    package.json
  molecules/
  organisms/

This is different than other posts I've seen that use a root stories/ directory -- that is not how we'd like to set up our repo, we'd prefer stories to live right next to the components they describe.

Setting Up Storybook

You can follow the same steps on the getting started page for setting up Storybook in a monorepo.

Once it's done, you should have a new folder at the root:

.storybook/
  config.js

If not, make sure that gets created. We need to make some changes to config.js to read stories within each package in the monorepo.

Configuring Storybook for a Monorepo

The key issue I ran into that prompted me to write about this is that we need to import stories using the Webpack context:

require.context('../packages', true, /stories.jsx?$/);

This prompts Webpack to scan a src directory for paths containing stories.js or stories.jsx anywhere in the string.

Since Webpack statically analyzes this code it means we cannot dynamically read the file system and iterate through each package directory (I tried that 😔).

There's another problem. Remember I mentioned each package directory has node_modules which means that the following paths will match the regular expression:

./atoms/node_modules/@storybook__react/src/stories/blah.stories.js
./molecules/lcov-report/_html/src/components/Hello.stories.js

And you can imagine more paths like that can match. Webpack will attempt to import these files into the bundle it generates but these will most likely cause build errors. That isn't what we want! We need to exclude everything but the src directory in a package when matching files.

The solution, as it turns out is fairly straightforward, since we have a convention where each package has components within a src directory, we really just need to match that inner src after the package name, so we can write a regular expression like this:

require.context('../packages', true, /^\.\/[^\/]+\/src\/.*stories\.jsx?$/);

Let's break it down:

^               # match beginning of path
\.\/            # the path will begin with a "./", like ./atoms
[^\/]+          # get the first path segment (match characters up to first /)
\/src\/         # ensure we match under the `src` directory
.*              # match any character
stories\.jsx?   # match anything with "stories.js(x)" in it
$               # match end of string

Here's an example using my favorite regex tool RegExr on which paths match and which don't:

Handy!

The Final Config

Here's our final config.js:

import { configure } from '@storybook/react';

function loadStories() {
  const req = require.context('../packages', true, /^\.\/[^\/]+\/src\/.*stories\.jsx?$/);
  req.keys().forEach(filename => req(filename));
}

configure(loadStories, module);

I hope this helps someone else and saves them the few hours I spent performing the correct rites to get this to work!

If you thought this was helpful, you can follow me or subscribe to my blog!

Originally posted at Kamranicus

Handling Safe Destructuring in TypeScript

Kamran Ayub — Wed, 26 Jun 2019 13:50:40 +0000

Originally posted on my blog at kamranicus.com

When migrating from JavaScript to TypeScript, you will often run into scenarios that seem difficult to statically type related to destructuring objects.

Destructuring an empty object

This pattern is showcased using the following code snippet, which reflects the semantics of some code we reviewed recently:

function transformSearchResults(payload = {}, queryParams = {}) {
  const { results } = payload;
  const { searchTerm } = queryParams;

  if (!results) {
    return payload;
  }

  if (searchTerm && isSearchPayload(payload)) {
    payload.transformedResults = results.map(r => ({
      ...r,
      anotherProp: true
    }));
  }

  return payload;
}

This function essentially takes a payload, transforms it, and returns the modified payload object.

Specifically, notice in the function arguments the expressions = {} which in JavaScript will set a default value of {} for the parameter if it is undefined. This is done because on the next 2 lines, we attempt to destructure and pull out some key props of the objects. If payload or queryParams is undefined then the destructuring would blow up and we don't want this code to blow up. That is pretty reasonable!

Converting to TypeScript

If we want to migrate this function to TypeScript, it would make sense to add a type annotation for each parameter like this:

export interface ResponsePayload {
  results: SearchResult[] | OtherResult[];
}

function transformSearchResults(
  payload: ResponsePayload = {},
  queryParams: QueryStringParams = {}
)

We are trying to annotate our types properly by telling TypeScript what types we expect these parameters to be. We've declared our API type ResponsePayload with a results property.

But alas, TypeScript will throw an error immediately:

Property 'results' is missing in type '{}' but required in type 'ResponsePayload'. ts(2741)

While this might seem wrong at first on the surface, TypeScript is actually pointing out a code smell in this function.

The reason that TypeScript doesn't allow this is because the ResponsePayload type has a results property that is required (cannot be undefined). We know this because we typed it that way, presumably because the API doesn't return undefined. If it did, we could change results to be optional.

When converting destructuring code to TypeScript, you will be encouraged to consider the code more critically than before, otherwise you will run into type errors.

Here's what I ask in this situation:

Can the function be simplified to pass a specific primitive value for the parameter?
If I need to pass an object, can I refactor the function to avoid it?

These questions are dependent on the specific case but in the majority of cases, you can usually remove the need to destructure by asking these questions.

For example, let's take it step-by-step.

Simplifying Function Parameters

Can the function be simplified to pass a specific primitive value for the parameter?

Here's the code again:

function transformSearchResults(
  payload: ResponsePayload = {}, 
  queryParams: QueryStringParams = {}) 
{
  const { results } = payload;
  const { searchTerm } = queryParams;

  if (!results) {
    return payload;
  }

  if (searchTerm && isSearchPayload(payload)) {
    payload.transformedResults = results.map(r => ({
      ...r,
      anotherProp: true
    }));
  }

  return payload;
}

A quick look will tell us that the answer is No for payload but Yes for queryParams.

Only results in payload is used but payload is also being mutated, so the function needs the object passed, let's set that aside.

For queryParams, only searchTerm is actually referenced, so let's simplify this function to pass only that:

function transformSearchResults(
  payload: ResponsePayload = {}, 
  searchTerm?: string) 
{
  const { results } = payload;

  if (!results) {
    return payload;
  }

  if (searchTerm && isSearchPayload(payload)) {
    payload.transformedResults = results.map(r => ({
      ...r,
      anotherProp: true
    }));
  }

  return payload;
}

Great! The rest of the code remains the same and we eliminated one unnecessary destructuring.

Approaches to Refactoring for Destructuring

If I need to pass an object, can I refactor the function to avoid it?

Right now the function requires payload to be provided directly. There are two approaches we could now take:

Specifying a default value for required properties
Removing the need to mutate an object so we can just pass results

Providing default values for properties

If we intend to keep the logic in the function intact, we need to provide a value for all required properties of ResponsePayload.

We can do this inline within the function which works well for a small list of parameters:.

function transformSearchResults(
  payload: ResponsePayload = { results: [] }, 
  searchTerm?: string)

All fixed; since we provide a default value for results which isn't undefined TypeScript is happy.

We could also choose to provide a default object for more complex situations:

const defaultPayload: ResponsePayload = {
  results: []
};

function transformSearchResults(
  payload: ResponsePayload = defaultPayload, 
  searchTerm?: string)

This works just as well but introduces a dangling object that might not add a ton of value. Can we remove the need for providing payload in the first place?

Removing the object altogether

The fact that the function mutates the original incoming object is a smell itself. There are cases where that makes sense but in this case, we are transforming results--we should just return the newly mapped results and push the concern of mutating payload to a higher-level.

function transformSearchResults(
  results: SearchResults[] | OtherResults[], 
  searchTerm?: string) 
{
  if (searchTerm && isSearchPayload(payload)) {
    return results.map(r => ({
      ...r,
      anotherProp: true
    }));
  }

  return results;
}

Nearly there. We will now receive an error because isSearchPayload was testing the payload itself. We have two options:

Modify isSearchPayload to inspect results
Push the concern of checking payload higher

We could certainly do option 1 but I like option 2 better. It will end up simplifying the results typing even more because we can know the results are search results! This also makes the function name much more accurate:

function transformSearchResults(
  results: SearchResults[], 
  searchTerm?: string) 
{
  if (searchTerm) {
    return results.map(r => ({
      ...r,
      anotherProp: true
    }));
  }

  return results;
}

There we go; we've totally removed the need for destructuring with this function by simplifying the requirements and avoiding mutation of objects.

Where did the complexity go?

By refactoring the function we pushed two concerns higher in the call stack:

Is this a search payload (isSearchPayload)?
Handling transformedResults for payload

That logic still has to exist somewhere but now it can be lifted higher. There is a principle at work here called the Command-Query Separation principle, which says:

"every method should either be a command that performs an action, or a query that returns data to the caller, but not both. In other words, Asking a question should not change the answer."

Before we refactored this function, it violated this principle because it both returned new results (a query) and had a side effect by mutating the object (a command). Now we've refactored it into a "query" function only.

If we had inspected the previous way this function was called, you would have seen this:

function (payload?: ResponsePayload) {
  if (!payload) {
    throw new Error("Missing response payload!");
  }

  payload = transformSearchResults(payload, queryParams);

  return payload;
}

This should raise a yellow flag since it is returning the object again which implies it may be mutating it (in other words, "it smells").

Now that we've refactored the function above, some responsibilities have been pushed higher, which may result in a change like this:

function (payload?: ResponsePayload) {
  if (!payload) {
    throw new Error("Missing response payload!");
  }

  if (isSearchPayload(payload)) {
    return {
      ...payload,
      transformedResults: transformSearchResults(payload.results)
    }
  }
}

We avoid mutating the payload directly instead opting to merge the new property in. We now have options to extract this logic, refactor it, etc. which you can decide!

Handling Nested Destructuring

If we're able to remove the need to destructure by simplifying functions that is a win but what if we really need to safely destructure and more specifically, in a nested way?

function handleData(data = {}) {
  const { meta: { field1, field2, field3 } = {} } = data;
}

This is slightly more complicated and subsequently harder to type and it should be. One thing I have come to appreciate about TypeScript is that it makes you feel the pain a little more which in turn encourages you to take a step back and question why the code is structured the way it is.

In this example, we can ask the same question we originally asked: Do we really need data or can we be more specific?

Keeping `data`

Let's say we must keep data as a parameter. If meta and all the field* properties can truly be undefined and are marked as so, this code will work.

As soon as one of them is non-optional, TypeScript will throw an error since we haven't provided defaults.

For example, let's say data is typed as:

interface Data {
  meta: Metadata
}

interface Metadata {
  field1: string;
  field2: boolean;
  field3: object;
}

meta is not optional, it must be provided so the code above will throw an error as no default meta value is provided and neither are the field* defaults. Yikes!

The best approach is to do a refactoring like we did above to simplify the parameters, if possible.

The next best thing is to remove the default:

function handleData(data: Data) {
  const { meta: { field1, field2, field3 } } = data;
}

This matches how we've described the types -- that no property can be undefined so there's no reason to use a default parameter anymore. If this matches what you expect, there's nothing additional to do.

What if in practice, things could potentially be undefined but we still want to ensure the types remain "pure"?

Then we should push the "guarding" of potentially undefined values higher up the stack:

function checkData(data: Data | undefined) {
  if (!data) {
    throw new Error("Data shouldn't be undefined");
  }

  return handleData(data); // No longer can be undefined
}

function handleData(data: Data) {

  // This is safe to do now
  const { meta: { field1, field2, field3 } } = data;
}

In general, you should guard as close to the source as possible. This keeps downstream functions simpler and with TypeScript, you can ensure they get passed values that don't need defaults to be provided.

Supporting partial objects

Let's assume that meta fields can be partially available, we can simplify and statically type the function like this:

interface Data {
  meta: Partial<Metadata>
}

interface Metadata {
  field1: string;
  field2: boolean;
  field3: object;
}

function (data: Data) {

  // This is safe now as `meta` can be partially undefined
  const { meta: { field1, field2, field3 } = {} } = data;
}

Now we've explicitly declared that meta can be partially defined. This does two things:

it allows the safe destructuring without compiler errors and,
it tells the reader to expect to guard against partially defined fields.
we have made an illegal state unrepresentable meaning that Metadata should not have any fields optional ideally but the function can support partial properties in an isolated way

Static types are documentation and now we've called out to expect that meta can have partial fields. It also allows us to safely set the default object to {} to avoid errors while destructuring.

The last resort: type assertions

There is a hammer we can use as a last resort. If we can't effectively refactor out destructuring or if we really need to force this pattern to avoid changing code, we can use type assertions:

function transformSearchResults(
  payload = {} as ResponsePayload,
  queryParams = {} as QueryStringParams
)

This will force TS to treat the empty object as the types we want--but this introduces potential for bugs as now we are opting out of the type safety. We are putting the responsibility of checking for undefined on the developer writing the function vs. the TypeScript compiler.

If you do this with ESLint rules enabled, you'll be greeted with an error:

Type assertion on object literals is forbidden, 
use a type annotation instead. 
eslint(@typescript-eslint/no-object-literal-type-assertion)

Again this is because it's best to avoid this in the first place. In order to get this to compile, you'll need to disable the error:

/*  eslint-disable-next-line @typescript-eslint/no-object-literal-type-assertion */
function transformSearchResults(
  payload = {} as ResponsePayload,
  queryParams = {} as QueryStringParams
)

At least now, you can later search for these disabled errors as an indication to revisit and refactor later.

Summary

When migrating to TypeScript, you will run into a lot of issues like this that on the surface feel like you're battling the type system but what I hoped to get across is that TypeScript is forcing you to think more explicitly about how your code is structured and what your intent is. It will force you to look beyond the scope of a single function and think more holistically about usage and context.

When you find yourself trying to disable rules or workaround TypeScript errors through type assertions, you need to take a step back and ask:

Is this the best way to structure this code or is TypeScript hinting that I may need to refactor it?

This type of mindset is a shift in thinking when working with TypeScript, especially when you've come from JavaScript. It may be painful at first but ultimately it will lead to better, hopefully simpler code.

If you're interested in furthering your understanding of principles like Command-Query Separation and refactoring code, I highly recommend the Encapsulation and SOLID course by Mark Seeman from Pluralsight.

You can also check out my collection of React and TypeScript content!

How to Get Started Using React with Typescript

Kamran Ayub ・ Mar 5 '19

#react #typescript #guides

Copying to the clipboard using React, TypeScript & Material UI

Kamran Ayub — Thu, 11 Apr 2019 18:53:24 +0000

It's common in apps to offer a way to "copy to clipboard" so users can paste content.

I whipped up a quick example using TypeScript and React to make such a behavior that can be applied to any React element using the render props pattern.

You can then use it like this, to wrap <Button /> or any other element:

<CopyToClipboard>
  {({ copy }) => (
    <Button
      variant="contained"
      color="primary"
      onClick={() => copy("some text!")}
    >
      Copy
    </Button>
  )}
</CopyToClipboard>

This is using the super simple clipboard-copy package.

You can override the <Tooltip /> props using the TooltipProps prop:

<CopyToClipboard TooltipProps={{ title: "Copied XYZ!", leaveDelay: 3000 }}>

Enjoy!

How to Get Started Using React with Typescript

Kamran Ayub — Tue, 05 Mar 2019 20:48:58 +0000

I got started using React with TypeScript about 2 years ago now and have been working on several projects both at home and at work that utilize both technologies. I'm loving it but I also see a lot of questions around specific patterns around using TypeScript with React. Many of these questions I've tackled in my projects but haven't sat down to write about, though I have talked about many of them.

In 2019 my goal was to write more about these topics and so far I have published three guides that cover the topics you need to get started from scratch and take you through statically typing React.

The benefit to sharing these guides is primarily to help people and to see if there's enough interest to warrant pitching a course or other long-form content on the topic! I've been a TypeScript user for over 5 years and I love how much it's growing in the community!

Guides

Disclosure: The guides are free to read without a Pluralsight subscription and I don't get any kickbacks. I've already gotten paid to write them initially which made them a good use of my time! Now I just want people to know they exist.

Getting Started with React and TypeScript - Zero to bootstrapped project using multiple ways like create-react-app, from scratch, Webpack, and Parcel.
How to Statically Type React Components with TypeScript - Covers patterns on statically typing React components, props, and state.
Composing React Components with TypeScript - Covers common patterns of composing React components such as inheritance, specialization, and render props.
How to Test React Components in TypeScript - Covers using Jest with TypeScript to test React components
Handling Safe Destructuring in TypeScript - Covers patterns on avoiding excessive destructuring and how to effectively handle defaults/fallbacks with object destructuring

Other resources I've created:

Building Scalable, Maintainable Apps Using TypeScript and React - Conference talk I gave recently on some patterns & practices I've picked up that I use in my apps.
Sample React & TypeScript Patterns Repo - Companion repository for my talk that has all the code samples.

Other resources I've seen:

Complete React & TypeScript Guide - This is pretty amazing work by

.ltag__user__id__259906 .follow-action-button { background-color: #093656 !important; color: #ffffff !important; border-color: #093656 !important; }

Piotrek Witek
React & TypeScript Cheatsheet Repo - Fantastic resource for lots of examples and recipes

I hope this helps others to learn the nuances of using TypeScript with React and I'll be sure to update this post as I put out more guides or find more resources!

Be sure to share other resources if you're also using React and TypeScript, I'd love to see them!

DEV Community: Kamran Ayub

Hacktoberfest: Can I ask a question?

Hacktoberfest projects expect newcomers

But will my question be welcomed?

Where should I ask?

Time to explore the cave, don't go it alone!

What to avoid

Always Be Asking

Controlling Browser Permissions in Cypress End-to-End Tests

kamranayub / cypress-browser-permissions

A Cypress plugin to set launched browser preferences including permissions like Geolocation, Notifications, Microphone, etc.

cypress-browser-permissions

Table of Contents

Usage

Install the

How to Use It

Writing an End-to-End Notification Test

How It Works

Selenium + Python Allow Firefox Notifications

How to allow or deny notification geo-location microphone camera pop up

What's Next?

Storyflow: Using Storybook to Build a Better... Game Engine?

Watch the talk

What is Storyflow?

One source of truth

Incentivizes writing more stories

Promotes more testability

Example

kamranayub / example-storyflow

Created with CodeSandbox

Storyflow Example

Getting Started

Why You Don't Need Types in JSDoc when Documenting TypeScript

Using Storybook in a Monorepo

Setting Up Storybook

Configuring Storybook for a Monorepo

The Final Config

Handling Safe Destructuring in TypeScript

Destructuring an empty object

Converting to TypeScript

Simplifying Function Parameters

Approaches to Refactoring for Destructuring

Providing default values for properties

Removing the object altogether

Where did the complexity go?

Handling Nested Destructuring

Keeping data

Supporting partial objects

The last resort: type assertions

Summary

How to Get Started Using React with Typescript

Kamran Ayub ・ Mar 5 '19

Copying to the clipboard using React, TypeScript & Material UI

How to Get Started Using React with Typescript

Guides

Other resources I've created:

Other resources I've seen:

Piotrek Witek

Keeping `data`