DEV Community: Dan Greene

When to avoid squishing dates together (a lesson in UI <--> backend team collaboration)

Dan Greene — Wed, 11 Oct 2023 17:48:04 +0000

One of the most dangerous places for bugs to occur is the API contract between the UI and the server. No, I'm not talking about breaking contracts. I'm talking about when the backend team tells the UI devs what the contract is going to be instead of making it a conversation.

In this article we'll discuss a scenario where, if I was in either devs shoes, I would recommend not using a Date at all.

What Are We Trying To Build?

Our customer wants a UI where they can schedule jobs to run daily.

They want to make sure that it always runs at the set time even if Daylight Savings is or is not observed.

Some Context First

At my current company (and at any company I would consult with), I encourage the UI developers to avoid Date in general and instead to use Temporal or js-joda (click here to learn why). And if you don't know what Temporal or js-joda is, you can read my primer here.

Our company wrote an in-house set of widgets that wrap react-date-picker and expose js-joda types (and you can too if you follow my guide).

When we did that, we made the decision to split react-datepicker into two separate components (date and time) for accessibility reasons. Namely, if you were navigating a date and time picker with a keyboard and a screen reader, you would be able to press "enter" on the selected day and you would automatically get the preselected time without knowing that you needed to make a time election. We solved that by making our pickers independent.

Before:

After (time get's moved to it's own component and removed from the day picker):

Let's Build It The Wrong Way First

Imagine a conversation like this:

Backend Dev: "You UI devs only have a Date object right?"
UI Dev: "Well no, we have Temporal coming up and Js-Joda..."
Backend Dev: "Cool cool. We already built the service and it only takes a Date. I thought you'd like that."
UI Dev: "I wish we had a conversation first."
Backend Dev: "Sorry! Here's the schema"

interface BadSchema {
    jobName: string;
    runTime: Date;
    /**
     * So that we can determine if runTime was in Daylight Savings Time
     */
    usersZone: string;
}

So the backend dev, who thought he was doing the UI dev a favor (he wasn't), goes to write the scheduler code.

By sticking to just a Date in the contract, the dev accidentally introduces a bug. Note: The backend dev is using Joda here since most recent Java versions have that js-joda API natively. But for consistency, this is Typescript.

const jobStartDateTimeFromUI = "2016-03-18T16:00:00Z";

// Convert that value that came across the wire into a useful type
const jobStartDateTime = ZonedDateTime.ofInstant(Instant.parse(jobStartDateTimeFromUI), ZoneId.of(usersZone));

console.log(jobStartDateTime.format(DateTimeFormatter.RFC_1123_DATE_TIME)); // Fri, 18 Mar 2016 17:00:00 Europe/Berlin

// adding a date unit of 2 weeks, crossing a daylight saving transition
jobStartDateTime.plusWeeks(2); // 2016-04-01T17:00+02:00[Europe/Berlin] (still 17:00)

// adding a time unit of 2 weeks (2 * 7 * 24)
jobStartDateTime.plusHours(2 * 7 * 24); // 2016-04-01T18:00+02:00[Europe/Berlin] (now 18:00)

What you'll notice there is that the server code broke the user's requirement that the scheduled job be run at the same time every day. But in this case it's going to be run at 6pm instead of 5pm. They wanted it sent at 5pm.

How Can We Prevent This?

In cases like this, you want the API contract to communicate as much as possible (within reason) so that the server can make informed decisions.

That means that instead of sending new Date().toISOString() the UI should be sending the first day of the scheduled job as a LocalDate, then the time they want it to run daily as a LocalTime, and then finally the ZoneId of the user so we can determine if Daylight Savings Time is even observed.

interface FormItems {
    jobName: string;
    /**
     * Most servers will accept YYYY-MM-DD format since it's ISO-8601 and JSON Schema has support for format: date and format: date-time (https://swagger.io/docs/specification/data-models/data-types/#format)
     */
    firstJobDay: LocalDate;
    /**
     * preserve this so that we can make sure that the scheduled job happens at the same time if we are or are not observing Daylight Savings
     */
    jobDailyTime: LocalTime;
}

interface ScheduledJobPostBodyDeserialized extends FormItems {
    /**
     * So that we can determine if firstJobDate was in Daylight Savings Time so we can ensure that jobDailyTime will remain the right time for any date in the future
     */
    usersZone: string;
}

Full Solution

Below is code for how the UI and the server would schedule this job. Note: I don't do any React code here since I'm trying to focus on just controller logic and the conversation between the UI and the backend over "the wire" (i.e. HTTP).

import {LocalDate, LocalTime, LocalDateTime, ZonedDateTime, ZoneId } from "@js-joda/core";

interface FormItems {
    jobName: string;
    /**
     * Most servers will accept YYYY-MM-DD format since it's ISO-8601 and JSON Schema has support for format: date and format: date-time (https://swagger.io/docs/specification/data-models/data-types/#format)
     */
    firstJobDay: LocalDate;
    /**
     * preserve this so that we can make sure that the scheduled job happens at the same time if we are or are not observing Daylight Savings
     */
    jobDailyTime: LocalTime;
}

interface ScheduledJobPostBodyDeserialized extends FormItems {
    /**
     * So that we can determine if firstJobDate was in Daylight Savings Time so we can ensure that jobDailyTime will remain the right time for any date in the future
     */
    usersZone: string;
}

// START OF MOCK UI CODE
()=>{

    // This would be React code normally, but for brevity this is what I have
    function getFormItems(): FormItems {

        throw new Error("Pretend implementation");
    }

    function prepareForServer(formItems: FormItems): ScheduledJobPostBodyDeserialized {
        const { firstJobDay, jobDailyTime, jobName} = formItems;

        // We have to pass the server the real offset instead of the value of ZoneId.SYSTEM since no one knows what that is besides js-joda
        // Read more at: https://js-joda.github.io/js-joda/manual/ZonedDateTime.html#the--code-system--code--zone-id
        const usersZone = Intl.DateTimeFormat().resolvedOptions().timeZone;

        const serverBody: ScheduledJobPostBodyDeserialized = {
            jobName,
            firstJobDay,
            jobDailyTime,
            usersZone
        }

        return serverBody;
    }

    function sendToServer(jobPostBody: ScheduledJobPostBodyDeserialized): Promise<void> {
        // psuedo-code

        // fetch({
        //     method: "POST", // *GET, POST, PUT, DELETE, etc.
        //     url: "fake url",
        //     body: JSON.stringify(jobPostBody),
        // })

        throw new Error("Not Implemented");
    }

    sendToServer(prepareForServer(getFormItems()));
}

// END OF MOCK UI CODE
() => {

    const mockDB: {
        jobs: ScheduledJobPostBodyDeserialized[];
    } = {
        jobs: []
    }

    function postNewScheduledJob(body: ScheduledJobPostBodyDeserialized){
        mockDB.jobs.push(body);
    }

    function runJob(job: ScheduledJobPostBodyDeserialized){
        console.log(`Let's pretend that we ran job named "${job.jobName}"`);
    }

    // We'd never do it this way, but it communicates how you'd work out Daylight Savings Time
    function tryToRunJobs(){
        // Create the time once so that it's fixed for all of the jobs
        const now = ZonedDateTime.now();

        mockDB.jobs.forEach(aJob => {
            const { firstJobDay, jobDailyTime, usersZone } = aJob;

            // You avoid the Daylight Savings Time problem by creating an instant with the component parseStrict
            const thisJobsTimeButToday = ZonedDateTime.of(
                LocalDateTime.of(firstJobDay, jobDailyTime),
                ZoneId.of(usersZone)
            );

            if(thisJobsTimeButToday.equals(now)){
                runJob(aJob);
            }
        })
    }

    // Again, we'd never do it this way, but it communicates the idea
    setInterval(tryToRunJobs, 1000 /* ms */);
}
// START OF MOCK SERVER CODE

And here's a link to this in TypeScript playground to help you noodle around with it.

Lessons

Send component parts of the Date if you want to ensure you handle Daylight Savings Time
UI developers should make sure that contract discussions happen long before each team starts working
Ideally, combine your teams into fully-autonomous team that has both backend and UI devs on it. But that's a topic for another day!

Why input masking is not accessible

Dan Greene — Wed, 16 Aug 2023 18:56:57 +0000

My team was asked recently to implement an accessible number input widget that utilizes masking.

As a UI Architect, I'm always willing to investigate if a feature such as masking can be accomplished in an accessible, performant, and high quality manner. Frankly, masking sounds cool and people have argued that it is necessary (source).

However, after trying a few of the libraries related to accessible inputs, such as react-aria's useNumberField and cleave.js, I have found that it is inherently unable to speak the truth to screen-readers and therefore it is not accessible.

But How Is It Not Accessible?

Let’s assume we have a masking scenario where the asterisk character that is illegal:

Let's see how that works with pasting a value and then how that works with typing a value,

If you paste “123*456” then the masking library will be unable to process any of it and will likely remove the entire thing which will leave the user with a blank input. React-aria does this, and you can see it by trying out their decimal example. There’s an even scarier example for which I used when I raised this as a bug to the react-aria team
If you type “123*456” then the masking library will let you type “123” then it will eat the asterisk (meaning the screen reader will say “asterisk” but the input will not show the asterisk) and then it will let you type “456” so what you’ll be left with is “123456” even though the screen reader will have told the user that “123*456” was entered. This is the scenario why I believe that masking is inherently not an accessible solution.

So what now?

Due to this, I now recommend that designers and developers opt to not use masking but to instead use error validation. This allows the user to type or paste what they want, but they will be told that what they typed was not allowed. In summary, it’s better to not “lie” to the screen reader, but instead to give good feedback to the user. Do they lose the nice formatting? Absolutely, but at least you've insulated yourself from ADA lawsuits and, more importantly, you've made your website more inclusive.

I'd love to hear people's thoughts in the comments. I should note that Giovani Camara has written beautifully about how to do your best to make masking accessible, but I would suspect that the test scenarios I mention above are still reproduceable. So, I would still recommend avoiding it.

Can you just combine region and language to make a locale?

Dan Greene — Fri, 11 Aug 2023 16:18:41 +0000

As I continue to grow my knowledge in internationalization (i18n), I've had the request from internal and external customers to support something strange.

"Hey, can we support the region of "Spain" but avoid taking on translation since translation is costly and requires hiring translators?"

As any developer, I thought "sure, I can do this!"

As it turns out, the more important question is not “can you do it” but “should you do it?”

How I Tried To Solve This

My first attempt to solve this was to look at date-fns since many UI developers use that for formatting. If date-fns had the “en-SA” locale or if it allowed me to pass it anyway, then my journey would be over. Sadly, I quickly found out that their locale support was limited to a pretty small set of countries and it is manually maintained as opposed to taken from a continuously updated source.

So then I started to look for a way to get the most up-to-date locale information. This search brought me to the browser supplied Intl API. Seemed pretty great (at first), except Intl doesn’t allow me to get the formats, which hurts my ability to communicate to the user what they are expected to type into a date input widget. I’ve since submitted this as a feature request, but since support would only come if the ECMAScript spec committee agreed to it and all browsers implement the enhanced spec, it would take a very long time to get a full solution.

After researching it a lot, I finally came to the source of truth, the CLDR. This is actually what the browsers use under the hood with Intl. By using the CLDR data directly, we have an opportunity to:

stay continually up-to-date with locales (since new countries/regions form and existing countries/regions change preferences)
get access to the formats for each locale’s dates, date/time, etc. so that we can inform screen reader users of the expected string to type (Which again, Intl does not support at this time)
get access to the source data so we can finally see if there is data for a locale like “en-SA”

But wait… the CLDR data doesn’t have “en-SA” either! So what should we do?

How Does CLDR Handle Missing Locales

So my immediate finding was: there is no "en-SA" locale, there is only "ar-SA." In other words, there is Saudi Arabia that speaks Arabic, but no Saudi Arabia that speaks English. This reflects reality. So why would we try to fake "en-SA"?

Let's see what would happen anyway. Luckily, the CLDR Elixir library has a very clear (but less-than-ideal answer):

When validating a locale name, Cldr will attempt to match the requested locale name to a configured locale. Therefore Cldr.Locale.new/1 may return an {:ok, language_tag} tuple even when the locale returned does not exactly match the requested locale name. For example, the following attempts to create a locale matching the non-existent “English as spoken in Spain” local name. Here Cldr will match to the nearest configured locale, which in this case will be “en”.

That one part is so important that it is worth repeating:

the non-existent “English as spoken in Spain” locale name

It doesn't exist.

While I like the clarity of their documentation, I am not pleased with the resolving that happens (i.e. "match to the nearest configured locale, which in this case will be 'en'"). So if you were to pass "en-SA", you don't get an error, you get an unexpected mutation.

So now that we know that the Elixir library for CLDR will silently resolve our fake "English Saudi Arabia" locale to English, let's see how Intl handles it.

Intl.DateTimeFormat("en-SA").format(new Date())
// '8/11/2023'

As you can see, it is using English United States standard for date where the month is first. This is NOT how Saudi Arabia prefers dates. They use the d‏/M‏/y pattern as shown in LocalePlanet, which is nearly identical to CLDR in my experience. So Saudi Arabia expects 11/8/2023 and yet if used our "fake locale" approach, we would be accidentally giving them 8/11/2023.

This would not be helpful to the user.

So What Should We Do?

Often the simplest answer is best for the user, and we have a simple answer:

Do not give your user to select a locale that does not exist in the CLDR.

Instead, give them some kind of UX feedback that helps them to find a locale that most closely matches their preferences.

For example, you could even give them a questionnaire.

Which of these number formats looks most normal to you? Which of these date formats look best to you?

Once they click on the radio buttons for that questionnaire, you can give them a list of commonly used locales that utilize those formats. For example, people who like to see months first, often will select "en-GB" for English as it is spoken in Great Britain. By doing this, you've:

🌈 helped your user to get the end result they want
🌈 you didn't have to mislead the user by giving them the false sense that their region/country is supported, which prevents a great many bugs
🌈you didn't have to write a bunch of fancy code just to workaround the problem. This would have led to hacky code.

Ultimately, honesty is the best policy.

Making your datepicker easier to work with

Dan Greene — Thu, 28 Apr 2022 16:57:42 +0000

Every programmers worst nightmare is (or should be) the scenario where a date based bug is caught years later. Why? Because that bug has now probably ended up persisting to your production database and now you don't just have to fix the code but you have to fix the data too, which is an extremely costly recovery that might require apologizing to your customers.

Which is why I was a pretty disappointed to see this bug still open in the react-datepicker issues list.

You might ask: why don't they just fix the bug?

Well... it's a logical bug, not a coding error. In fact, this "bug" is probably in every date picker library on the internet... unless it uses the techniques I will be showing below.

Thankfully, you can prevent logical errors by using domain driven design and types that help enforce the logic (stay with me, don't get scared off by types/OO/DDD concepts).

So follow along and I'll show a way to continue to use the robust and highly-accessible react-datepicker library without introducing logical bugs that are hard to track down.

How would that help?

"say what you mean, mean what you say"

Clear communication is vitally important. Let's imagine that I want to buy my friend a birthday card. So I ask them what their birthday is. Should I expect them to respond with "My birthday is January 1st 1990 at 2:13am" or would you expect them to say "January 1st"?

Of course you wouldn't expect to get the hours or minutes back because you didn't ask that person for the moment that doctor announced the birth of the baby.

I like to imagine that the same clarity of communication can and should be applied to programming.

So a birthday is a LocalDate and the moment they were born is a ZonedDateTime. However, if I wanted to know the moment they were born without time zone information, it would be an Instant (think ISO format in the GMT time zone).

By specifying what you want in the code, you make it clear what is accepted. Would you want someone to pass a number when you really wanted a string? Being clear on your inputs allows you to catch errors at compile time instead of finding the bug in production or having to write expensive unit tests (that might be brittle and therefore leave you with the bug in production anyway). Follow along below to see how you can prevent bugs by simply saying "no, I do not accept a Date, I only accept a LocalDate."

Hold up, I have to learn new terms like LocalDate?

Sure, if you want to prevent extremely expensive bugs in your code you do. But don't worry, once you learn them it's hard to not think in the terms of Instant, LocalDate, and ZonedDateTime. And I have a cheat sheet for you on my prior article if you want to catch up the terms.

And frankly, you should take 2 minutes to learn the terms since the future is coming when it will be a code smell to use Date or even a library that exposes a Date. That's because the JavaScript community is finalizing the Temporal RFC spec. A polyfill is being worked on already, but soon it will be in all of our browsers so you won't need to use the native JS Date class. And Java has had these concepts since since Java 8.

While we wait for the Temporal RFC spec to be adopted and implemented in browsers, we can use JsJoda which implements the Java 8 / Threeten spec in JavaScript/TypeScript since JsJoda uses all of the same concepts.

Okay, show me

So first, a simple example of how this works. Using our "What is your birthday" example, we can mock up this code. Note: I'm using TypeScript because it enforces the concepts at compile time, but the JsJoda library itself enforces the concepts at runtime so that we get the best of both.

This is essentially the conversation above but in code:

import {LocalDate} from "@js-joda/core"

// Notice that the type of the parameter forces us to box the type first
const saveDateToDatabase = async (day: LocalDate) => {
  await db.save(day)
}

const whatIsYourBirthday = async (inputFromKeyboard: string) => {

  try{
    // Okay, it's time to try to see if the string can become a LocalDate
    const day = LocalDate.parse(inputFromKeyboard);
  } catch(err){
    throw new Error(`It seems like what you entered is not a date.
      Maybe it has too much (like it shouldn't have the year or time).
      See the full error: ${err}`);
  }

  await saveDateToDatabase(day);
}

If you want to play around with JsJoda, I'd recommend opening up the homepage since it has the library loaded into the window object for you to experiment. Note: the doc pages do not.

I think you'll find that the learning curve is a bit steep; however, the cost savings long term are significant. Think of it as a "slow down so you can speed up" type of situation.

Okay, I'm sold... but can we make it easier?

If you like the idea of clarifying when you mean a day vs an moment in a time zone then you still might want to make it easier on yourself to start with those terms. You might not want to have to do that necessary conversion between the JS standard Date object when you're in a callback of a form element. I can't blame you.

So what if you never had to use Date at all?

The following is a CodePen that demonstrates a way to encapsulate the conversion so that you're always dealing with the safer concepts.

Essentially you wouldn't every directly render react-datepicker, but instead would render a custom LocalDatePicker.

Notice that the above CodePen uses LocalDate because the date picker does not allow the user to select the time.

So let's show another example but this time a ZonedDateTimePicker where we're using react-datepicker's showTimeInput prop. An example where this would be helpful would be an insurance adjuster calling you to ask "what time did your car get into a collision?" You would want to know the ZonedDateTime that this occurred, so that's the JsJoda type we'll use in the CodePen.

It's important to call out that I'm not showing an example of an InstantPicker since the question being asked is "what time did your car get hit in your timezone?" So that's why it would be a ZonedDateTime. Again, don't get scared by the differences between the concepts-- once you speak the language you'll find it hard to use ambiguous terms like "date."

I'd encourage you to look at the source code of that CodePen above (under the "Babel" tab); however, to understand how this encapsulation solves the logical bug, consider this portion:

if (!!selected && !ZoneId.from(selected).equals(zone)) {
  throw new Error(
    `The provided date ("${selected}") was not in the expected ZoneId ("${zone}")`
  );
}

What that does is ensure that if a value for the selected date comes back in a different time zone / offset, the component will stop in it's tracks. It's not the ideal behavior for your users, but it's a good example of how it can prevent a bug from going un-noticed. This is only possible due to a beautifully expressed domain language that expresses the concept of a Zone. You can't do that with regular ole' Date!

Summary

If you chose to adopt this approach, you and your peers will be able to have a clear conversation about if the current feature you're writing needs ZonedDateTime or LocalDatePicker. By doing that you'll protect your software and your users for years to come.

Attribution

Note: I would probably build this into a library but I'm maxed out on other maintainer work at the moment. So if you choose to turn my codepen into a library, please just share a link to this article! :)

By the way, you know that hypothetical scenario I mentioned at the top? That actually happened to me. I had to spend nights and weekends for over a month to fix the incorrect data in the database caused by a previous, long-gone developer. Thankfully, a mentor shared with me the concepts I described in this article so I was able to improve the code more easily. So be like that mentor and share this article with friends and coworkers so they can prevent bugs too! :)

Temporal/Joda concept breakdown

Dan Greene — Thu, 28 Apr 2022 16:53:35 +0000

So, you really want to get off of the deprecated MomentJS library and you're excited about the new JavaScript proposal for Temporal . This article is designed to help you get familiar with the types for Temporal. Given that Temporal has not been accepted by browsers yet, I'm including the https://js-joda.github.io/js-joda/ types since they are 99.99% the same. Sure, the APIs for JsJoda are different, but you can use JsJoda while you wait for Temporal to be adopted.

LocalDate / PlainDate

( JsJoda docs | Temporal RFC docs )

represents a calendar date that is not associated with a particular time or time zone, e.g. August 24th, 2006.

Note, Temporal calls this PlainDate and Joda calls this LocalDate.

Stringified version:

"2022-04-28"

Real World examples:

the day you were born
the day you first tried icecream

ZonedDateTime

( JsJoda docs | Temporal RFC docs )

A date-time with a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30+01:00 Europe/Paris.

Stringified version:

"2022-04-28T11:49:57.999-04:00[America/New_York]"

Real World Examples of ZonedDateTime:

"When will we be landing in New York City?"
- The person asking this likely wants to know what the time is relative to that offset (note timezones and offsets are different). Like does the asker want to know what time it is in New York City? Or do they want to know what time it is on their not-automatically-updating wrist watch since that's what is going to help them understand when they need to get sleep?
"What time did your car get hit by another car?"
- the insurance claims adjuster probably wants to know what time of the day it was in that area so they can determine what time of the day in Philadelphia has the most traffic accidents. It would be very hard to determine that if all you had was an Instant since Instants do not have timezone/offset information.

Instant

( JsJoda docs | Temporal RFC docs )

A Temporal.Instant is a single point in time (called "exact time"), with a precision in nanoseconds. No time zone or calendar information is present. To obtain local date/time units like year, month, day, or hour, a Temporal.Instant must be combined with a Temporal.TimeZone instance or a time zone string.

Stringified version:

"2022-04-28T15:49:57.999Z"

Real World Examples of Instant:

Instant (in my experience) is pretty much exclusively used for sending a datetime string over HTTP. Some times you just don't need to store the offset, so that's why Instant is helpful.
- If you do need to store the offset, ZonedDateTime since that will keep the offset.

LocalTime / PlainTime

( JsJoda docs | Temporal RFC docs )

represents a wall-clock time that is not associated with a particular date or time zone, e.g. 11:49 AM

Stringified version:

"11:49:57.999"

Real World Example:

What you would answer with if a friend (who lives in the same town) asks "What time do you want to meet at the restaurant?"

Other types

Joda and Temporal both have many other types that you might need to help with conversions between the above concepts.

For instance, LocalDateTime (or Temporal's PlainDateTime) is a type I can't imagine every using in the real world. Why would I want to know the date and time but without the timezone? Because with LocalDateTime you don't even know if the time is relative to Zulu/GMT or if the moment occurred is in New York City.

Personally, I have found that when you need to know about these more rare types (like LocalDateTime or OffsetDateTime), you'll have end up naturally discovering them through StackOverflow or through the library docs when you're looking up how to accomplish something. For now, get familiar with the types above and the rest you'll learn as you go.

Visual Depictions

When you see the types here, you realize two things:

The people behind the Temporal spec didn't like the word "Local"
We should have had these terms at the start of Javascript!

How to properly deprecate

Dan Greene — Thu, 10 Feb 2022 15:42:09 +0000

Why would I deprecate?

Sometimes you release a function or widget with your library and you later think "wow I could have done that better." After all, if you're not looking back at your old code and thinking "who wrote this" then you're not improving as a developer.

But... you can't just delete that function in your next library release. If you did that, your consumers would get 💥 a in their build, or (if they're not using static compilation like TypeScript) the end user will get a bug in production. 🤕

So you've got to give your library's consumers some advanced notice.

How to do it

Make a plan to only remove the item from your next major version (i.e. x.1.1) This is because users only expect functionality removal in major versions due to how SemVer works.
In your next patch version (i.e. 1.1.x), plan to do the next steps
Add a @deprecated JSDoc tag to the JSDoc comment for that function/class/component. See an example of how to do that in the JSDoc website.
Since the JSDoc tag only helps developers if they have eslint-plugin-import/no-deprecated and/or eslint-plugin-deprecated-props installed, you should do the developer a favor by using console.warn when that function or property is used. I'll provide an example below.
Here's the most important step: tell your consumers about the upcoming change. That means updating your release notes to explain that the item is going to be removed soon. It also means sharing it with your twitter followers, your Slack channel, dev.to, and (if your library is private) share it in your company's internal communications. Do you have to do this last step? Sure, you could skip it since the steps above will give runtime and compilation time feedback... however, why not give your users advanced heads up?

Bringing it all together

Here's how you'd deprecate a function:



/**
 * this is what you get when you trust a mouse talk show
 * @deprecated please use our new function mult instead
 * @returns {Number}
 */
export function multiply(a, b) {
  return a * b;
}

Here's how you'd deprecate a property in a function. This is only possible in TypeScript (see source).



interface ComponentProps {
  /**
   * Some prop that is going to be removed in the future
   * @deprecated This will be removed soon in favor of colorHex
   */
  colorName?: string;
  colorHex: string;
  someOtherProp: string;
}

/**
 * Note that the @deprecated prop is used in the implementation
 * since it should still work. This does not throw a warning per se.
 */
const Component = ({ colorHex, colorName, someOtherProp }: ComponentProps) => {
  if(colorName){
    console.warn('colorName is deprecated. Please use colorHex instead');
  }
  const colorClassName = determineClassName(colorHex, colorName);
  return <div className={colorClassName}>{someOtherProp}</div>;
};

Side note, isn't it cool that VSCode shows that colorName is deprecated by putting a strikethrough style on it?

Any questions?

Given how quickly the "developer experience" (DX) area is evolving, I'm sure there are improvements on this approach. So please comment below if you have suggestions, questions, or tips. Thanks for reading! :)

When React Hooks "just clicked" in my head 💡🤩

Dan Greene — Wed, 19 May 2021 20:43:08 +0000

A lot of people writing React think that when they initialize a variable, it's going to stay that way every time.

For instance, let's imagine a very simple React component.

const Demo = ()=>{
  const name = 'Bob';

  return <div>Hello: {name}</div>
};

You might come away thinking that the name variable will always be the same piece of memory no matter how many times the Demo component is rendered.

In reality, React calls that Demo function every time it renders the parent components that contain the Demo component.

Wait a second...

Yes, that means that name is going to be a new variable every time Demo is called (which is every time React needs to render it).

So, it's almost like each time Demo is rendered, the name property is born again. That realization is what helped make React Hooks click. Hooks lets you make name immortal (for the life of the browser tab being open).

What if I wanted it to stay the same?

Well, that's what hooks were more or less invented for. Hooks predominantly are about allowing React devs to use simple functions to describe their creational patterns but to allow these functions to express stateful concerns.

Before hooks, you would have had to use a Class to describe a component that has state.

But with React Hooks like useRef, you can say "hey React, would you mind keeping this variable around?"

K, but let me see this in action

Sure! Here's a demo that shows starts off showing how the Demo component is essentially stateless and therefore the name property can never be the same between renders.

If you follow along the comments in the code example below, you'll be able to uncomment the correct lines to show how you can inform React of which pieces you want it to keep the same between renders.

Stop dividing microservices the wrong way with this 1 simple tip

Dan Greene — Wed, 24 Feb 2021 19:59:25 +0000

If one of the promise of microservices is greater development is greater productivity, then why do most companies find that microservices are slowing them down?

The answer is often: we divided the monolithic application into microservices at the wrong boundaries.

Where did we go wrong?

Here's the tip:

Stop using domain decomposition as your sole criteria.

Hold on a sec, I thought that domain decomposition was the standard way to break up a monolith? Why is it a problem?

While it's important to understand the business needs, there is a better technique (read below). The reason why domain decomposition alone can be dangerous is because it can cause:

slow delivery of value as a result of having to deploy and promote multiple microservices whenever a new feature is developed
late feedback of bugs due to the distributed nature of microservices
- put nicely, this means:

Okay, so how should we divide the monolith?

Ask yourself this question:

If I divide the monolith this way, will I have to deploy two or more pull requests every time I want to make a substantial change?

I do not claim to be an expert in this matter. But I'll let my favorite architect speak to this topic in this tweet:

Stefan Tilkov

@stilkov

“Microservices” are building blocks of an architectural style where deployment boundaries are a first-class software architecture principle

08:29 AM - 09 Sep 2016

Surely, there are many experts who have spoken on this (and I'd encourage you to share your favorite links in the comments). However, I have lived through the monolith -> microservices transformation at a few companies.

What I've learned is that you have to constantly think about developer productivity when considering how you'll break the monolith into separate microservices.

How do I factor developer productivity into my designs?

Solution 1: Pull request heatmap

One way is to look at your previous pull requests (PRs) in the monolith.

Ask yourself, "which of the proposed microservives are being touched with this change?"

That "gut-level check" question can be answered somewhat objectively by looking at commit history. If you already are in a "nano service" landscape where you microservices have been sliced-and-diced to thinly, you can use Github commit graphs to see the frequency of commits to each microservice. You can then turn that into a heatmap to see which microservices

In the absence of git commit data, you'll need to rely on thinking through the flows of functionality and which parts of the system are touched. This is essentially a simplistic version of event storming (which is beyond the scope of this article), but we'll look at how an event passes through the system. The emphasis is on functionality as opposed to entities (i.e. like the distinction between typical hierarchical object oriented design versus functional programming).

For instance, imagine that we have one PR that introduces the functionality to let an end user check if a pet is ready to be picked up from their haircut appointment. In the past, the sequence diagram for this would have looked like one large box since it was just a monolithic application.

But when you think back to the PR for this schedule lookup feature and you consider the potential microservices that would be necessary, you might see that your "customer" microservice and your "permissions" microservices have to be touched whenever you want to introduce a change.

Let's further this point by introducing a feature that involves paying for the haircut. The sequence diagrams again that your deployment boundary is essentially the entire system. So why even have separate microservices?

Solution 2: look through the lens of testing

While reviewing the flow of functionality in your system, you can also think: "How am I going to test this?"

Deeper questions for that same thought process involve:

if we separate the customer DB from the permissions DB, is there a way for us to test the end-to-end functionality easily?
if we don't have end-to-end tests for this functionality, are we willing to invest in the cost of contract testing?
- are we willing to make sure that every one of our APIs is upholding that contract and updating all consumers? (I mean, you always should, but this might not be achievable for smaller companies)
if don't plan to use end-to-end tests or contract testing, are you willing to invest in running containerized versions of each dependency in the PR to get fast-feedback?
if you can't find any way to get fast-feedback (i.e. the PR being rejected by a failing automation test), are you willing to let bugs get into the hands of the end user?

Hopefully the answer to the last question is always "no."

So what would the ideal breakdown of the monolith look like?

I don't have a simple, general answer. But I feel confident that you will be able to define better boundaries than ever before if you ask yourself those test-driven questions above and continue to place emphasis on flows not entities.

Make 2020 brighter --> send an open source maintainer some gratitude

Dan Greene — Wed, 09 Dec 2020 02:32:36 +0000

Hi there. We all know that practicing gratitude is one of those Oprah magazine tricks to getting happier.

So in the spirit of that, why not send some gratitude to an underappreciated library and/or it's maintainers that you feel could use a little boost of happiness. Being a library maintainer can be a tough and thankless job since you rarely get to see the impact of your work. Let's change that. :)

Which library comes to mind for you?

Wow! Cypress can run unit tests! 🥳

Dan Greene — Thu, 12 Nov 2020 21:09:09 +0000

Seriously, I am super excited about this. You can write unit tests in Cypress without even having to run a web server. That makes Cypress the ideal tool for testing a JS/TS library that is meant to be used in the browser.

I know what you're thinking... "I've got {some other testing library}, why would I need to use Cypress?"

Well, if you haven't tried it yet, Cypress really is rather lovely.

It's not just that Cypress is super user-friendly and easy to learn. No, there's something incredibly important that Cypress does that other tools don't do (by default). Cypress actually runs in a browser.

Huh? Why not Jest?

And as great as Jest is (and it has basically won the unit testing war), there's a not very clearly advertised problem with Jest...

... Jest doesn't run code in a browser.

It runs in JSDom which is really just a wrapper on NodeJS that mocks out different browser APIs.

Which means... a test can pass in Jest but fail in the production code. That's not what you want out of your test automation code. You want confidence.

But hold up, what about Karma?

Ah, I see you've been doing this for a while. Yes, Karma is/was a thing and in some cases is still quite popular.

But after spending more than a few hours trying to get Karma set up, I eventually bailed. I guess I've been spoiled by the incredibly easy setup of Jest and Cypress.

Alright, I'm sold. What do I need to do?

The Cypress.io team has made some pretty useful examples of Cypress unit testing, but the one that has me most excited is the example where you don't need to run a web server.

It's really as simple as:

Install Cypress
Run npx cypress open to get the folder hierarchy set up
(optional) If you want type safety, add a tsconfig.json file to the ./cypress folder and rename the spec files from .js to .ts
import your library (or whatever software you're testing) at the top of the test file

I honestly can't believe that it's as simple as just importing the function you want to test.

Caveat

This is a little bit harder for React code, so the steps I provided above are more for testing "vanilla JS/TS" code (i.e. code that isn't specific to any UI framework).

But again, the Cypress.io team has you covered with example of React unit test examples too.

Wrap Up

Please give this a try and let me know what you think of it. Ultimately, I feel incredibly grateful to be developing code at a time when we have such wonderfully fast and easy to use tooling at our disposal.

I'd love to hear what your experiences are, so please share! :)

P.S. If you're already a pro with Cypress and you're looking to level-up, learn how "fixture factories" can improve your test code.

Does your UI use "build once" for promoting to environments?

Dan Greene — Wed, 11 Nov 2020 18:02:28 +0000

Please comment below with which approach you take:

build once and then promote multiple times per environment
build every time you want to move code to an environment

For those of us who have worked at medium to large companies, it's not uncommon to have multiple environments like:

Dev -> QA -> Staging -> Production

What I want to know is, do you follow an approach similar to the "Twelve Factor App" guide where you build once and then promote that artifact? Or do you build the UI code each time for every pipeline?

Here's an image of taken right from the "Twelve Factor App" guide that I find helps to demonstrate the goal.

But typically that's pretty hard to do with UIs where the configuration is typically in webpack (meaning that the config is "baked" into the UI code at build time).

So which approach do your teams use?

How to eliminate "magic strings" with a fancy Typescript trick

Dan Greene — Thu, 01 Oct 2020 21:11:23 +0000

One of the first things you learn as a professional developer is that magic strings are bad. Why? 🤔 Because typos stink and can really ruin an application in a way that's hard to track down.

For instance, my team and I were use Storybook to display all of the UI widgets that we have available in our library. And there were a couple of times where we misspelled something only to find that one of the widgets was missing from the final output.

The Ideal Goal

Ideally a developer wouldn't have to remember the full path or the agreed upon folder names for storybook. If we rely on memory, they're going to type things wrong.

The Solution?

We'll create a function that lets developers "crawl" the paths to create a concatenated path.

For instance, if we wanted the folder structure in the image below, I'll show you how we would initialize the title.

That would mean inside the dateAndTimePicker.stories.tsx file, I would initialize the title like this:

const title = makeTitle('Widgets')('Temporal')('Date Range Picker').finalize();

The coolest part of this approach is that you can't spell "Widgets" wrong... Typescript won't let you. And you also get Intellisense to help you remember what options are allowed.

Let's show how to make this possible.

Step 1: Store the hierarchy in a series of nested objects

This first step is basically the same as how you would eliminate "magic strings" in any project-- by creating constants. But the cool part here is that Typescript naturally lets you store a hierarchy of constants as a series of nested objects. You'll see the power that gives us later when we start to use keyof to create smarter types.

const headingsMapObj = {
    Widgets: {
        Temporal: {
            'Date Range Picker': 'Date Range Picker',
        },
        Input: 'Input',
        Checkbox: {
            'Single Checkbox': 'Single Checkbox',
            'Checkbox Group': 'Checkbox Group'
        }
    },
    'An Introduction': {
        Welcome: 'Welcome',
    },
    Patterns: {
        Spacing: 'Spacing',
        Flow: 'Flow'
    },
} as const;

Step 2: Turn this into a type

type HeadingsMap = typeof headingsMapObj;

Step 3: Create the path builder

const makeTitle = <K1 extends keyof HeadingsMap>(level1: K1) => {
    const paths: string[] = [];
    function pushKeyIfStringOrThrow(input: string | number | symbol){
        if(typeof input === 'string'){
            paths.push(input);
        } else {
            throw new TypeError(`Unsupported type: ${typeof input}`)
        }
    }

    const finalize = () => {
        return paths.join(' / ');
    };

    pushKeyIfStringOrThrow(level1)

    const builderFnLevel2 = <K2 extends keyof HeadingsMap[K1]>(level2: K2) => {
        pushKeyIfStringOrThrow(level2)
        const builderFnLevel3 = <K3 extends keyof HeadingsMap[K1][K2]>(level3: K3) => {
            pushKeyIfStringOrThrow(level3)
            const builderFnLevel4 = <K4 extends keyof HeadingsMap[K1][K2][K3]>(level3: K4) => {
                pushKeyIfStringOrThrow(level3)
                return {
                    finalize
                };
            };
            builderFnLevel4.finalize = finalize;
            return builderFnLevel4;
        };
        builderFnLevel3.finalize = finalize;
        return builderFnLevel3;
    };
    builderFnLevel2.finalize = finalize;
    return builderFnLevel2;
};

And that's it! :)

Okay, cool... but how does that work?

It would probably take a while to explain how and why that works. And I'll be honest, it's taken me a long time working with Typescript to create something this wild. And if you're interested in a detailed breakdown of how the above code works, reach out in the comments and I'll create a follow up post.

But the basic idea is that the keyof type operator creates a more strict type that is more narrow than a string.

So in the case of a type like:

const exampleObj = {
    'hello': 'Bill',
    'goodbye': 'Ted'
} as const;

We can create a type that only allows 'hello' | 'goodbye' by writing:

type exampleKeys = keyof typeof exampleObj;

Here's the next bit of magic. Let's say we wanted to get a type that was only 'Bill' | 'Ted'.

All we'd have to do is write:

type Example = typeof exampleObj;
type ExampleValues = Example[keyof Example];

Note: if ExampleValues is still string when you hover over it, you might have forgotten to add as const to the end of the exampleObj instantiation. Another dev.to user has a great explanation of what makes as const work.

Wrapping Up

Thanks for coming along in this brief journey on why Typescript is so fun and how it can solve unique code problems that no other language can solve. :)