DEV Community: Frendy Guo

Narrow Down Types With Typescript Generic Constraints

Frendy Guo — Sun, 09 Jan 2022 06:25:51 +0000

Any statically-typed language supports generic, Typescript is no exception. With generic, we can write a flexible type signature that encourages reusability for our functions. Without it, functions are restricted to one specific data type which in turn, makes it hard to reuse.

function createArray(items: string[]) {
  return new Array().concat(items);
}

In the example above, the function createArray accepts an array of string and outputs an array of string. Depending on the use case, but we can improve this function by giving it a generic type such that it accepts more than just string type.

function createArray<T>(items: T[]) { ... }

createArray<string>(['Hitchhiker', 'Guide', 'To', 'The', 'Galaxy']); ✅
createArray<number>([42]); ✅
createArray(['Life', 42]) ✅ // `string | number`

With generic, we can enforce our createArray function to accept and return a specific type.

In addition, omitting the type will cause the createArray function to infer the type from the argument (['Life', 43] is translated into string | number). This looks great, our function can be reused with different type signatures.

However, a lot of times when writing a generic function, we might have some prior knowledge about how our function works underneath and therefore we can narrow down the type. In Typescript, this is called Generic Constraint.

Understanding Generic Constraint

A generic constraint is simply a way to put some constraints to a type. Suppose we have a generic function like this,

function getStuff<T>(arg: T) {}

getStuff("Hitchhiker's Guide to the Galaxy"); ✅
getStuff(42); ✅
getStuff([]); ✅
getStuff({}); ✅
getStuff(null); ✅
getStuff(undefined); ✅

You'll notice that null and undefined are allowed here, it might be what we wanted, but I'm sure most of the time these are invalid inputs. To solve this, we can put a constraint on our generic type to disallow empty value.

function getStuff<T extends {}>(arg: T) {}

getStuff("Hitchhiker's Guide to the Galaxy"); ✅
getStuff(42); ✅
getStuff({}); ✅
getStuff([]); ✅
getStuff(undefined); ❌
getStuff(null); ❌

In the example above, T extends {} means that T can be any type that is a subclass of {} (an object), in Javascript string, number, array and object are all subclasses of object, while undefined and null are not, therefore they are disallowed. This is what generic constraint syntax look like, by extending the T type.

Generic Type With Specific Behavior

Somewhere in our function, we might invoke a specific method of the argument, but with generic, we can't be sure such property exists. Therefore we need to further constraint our function to only accept an argument with a specific signature.

type Lengthwise = {
  length: number;
};

function getLength<T extends Lengthwise>(arg: T): number {
  return arg.length();
}

getLength("Hitchhiker's Guide to the Galaxy"); ✅ // 6
getLength(42); ❌
getLength({}); ❌
getLength([]); ✅ // 0
getLength(undefined); ❌
getLength(null); ❌

In the example above, only string and array have property .length while the rest are disallowed.

Get What You Ask For

Now that we've gained some ground, let's see how we can perform a more advanced constraining with Typescript. Suppose we want to create a function that accepts a custom shape and return the exact same shape like this,

const {
  foo,
  bar
} = getStuff({
  foo: '',
  bar: ''
});

This is a perfect case for generic constraints. Let's start by defining our custom type.

type CustomObject = {
  foo: string;
  bar: string;
  baz: string;
};

Our custom type has three fields: foo, bar, and baz. The argument can be a full set or a subset of CustomObject, to solve this we can use the Typescript built-in type Partial.

function getStuff<T extends Partial<CustomType>>(arg: T): T { ... }

const {
  foo, // ✅ 
  bar, // ✅
  baz // ❌ `baz` does not exist on type `{ foo: string; bar: string; }`
} = getStuff({
  foo: '',
  bar: ''
});

Perfect! Our function returns exactly the shape we asked for, no more and no less. Note that the empty string '' is simply a placeholder value to fulfill the object shape, it doesn't actually do anything (we can customize it though).

Alternatively, if you dislike the fact that we use an object to define the shape, we can also do it like this,

type StuffRequest = keyof CustomType;
type StuffResponse<T extends StuffRequest> = {
  [k in T]: CustomType[k];
}

function getStuff<T extends StuffRequest>(...args: T[]): StuffResponse<T> { ... }

const {
  foo,
  baz,
  bar // ❌ `bar` does not exist on type `StuffResponse<'foo' | 'baz'>`
} = getStuff('foo', 'baz');

Which one is better, you decide.

Dealing With Test Doubles

Frendy Guo — Fri, 24 Dec 2021 15:39:53 +0000

No doubt testing is one of the most important parts of software development. Many tools have been developed to make the process of testing easier. But often time engineers are reluctant to write test because of two reasons, brittle and slow tests.

Test is considered brittle if it fails due to unrelated change that does not introduce any bugs on production codes. This can happen if the test is validating implementation details rather than the public APIs.

On the other hand, slow test can be due to many reasons. Maybe the test is performing an HTTP request that adds up the latency, maybe the test has to simulate delays in order to satisfy certain conditions, and so and so. Few of these are fine, but imagine hundreds of test cases with each adding a few seconds to the runtime, the test will likely take hours to finish.

In such cases, test doubles can be handy.

Test Doubles

If the term test double feels rather strange to you, that's because we have been mostly using the word "mock" to refer to the whole family of objects that are used in test.

Just like how a stunt double stands in for an actor in order to perform physically demanding stuffs, test double is used as a substitute for the real implementation. A test double is simply a stand-in object or function that behaves similarly to that of a real implementation. It is an ideal choice when using the real production service is simply not feasible.

Can you imagine the incurred cost of having to actually proceed with payment on credit-card payment service every time we run a test case?

There's a short blog post titled The Little Mocker written by Robert Martin (also known as Uncle Bob) that hilariously explains the relationship between various kinds of test double.

In short, test doubles are comprised of dummies, fakes, stubs, spies, and mocks. Each enables a different style of testing.

Out of these, Dummy objects have no real behavior, they're only passed around to fulfill parameter lists, while the rest work a bit differently. It is particularly helpful for engineers to understand how each technique work and what are the downsides of it.

Fakes

First, we have fakes, a lightweight version of an API, object, or function. Fakes behave similarly to real objects, they have business behavior but usually take some shortcuts in order to simplify.

An example of this would be an in-memory database that stands in for real database.

Fakes can be constructed without help from mocking frameworks such as Jest or Sinon. An example of a fake object in Typescript,

interface Payload {
  username: string;
  password: string;
}

interface Authentication {
  isAuthenticated: boolean;
  authenticate: (payload: Payload) => void;
}

class FakeAuthentication implements Authentication {
  isAuthenticated: boolean = false;

  authenticate(payload: Payload): void {
    if (payload.username === 'Bob' && payload.password === 'Ross') {
      this.isAuthenticated = true;
    }
  }
}

const fakeAuth = new FakeAuthentication();

const payload = {
  username: 'Bob',
  password: 'Ross'
};

it('test fakeAuth', () => {
  fakeAuth.authenticate(payload);
  expect(fakeAuth.isAuthenticated).toEqual(true);  // ✅
});

With fakes, real implementation can be replaced with a fake one. In the example above, we created a fake authentication class that closely follows the authentication API contract, this class can later be used as a replacement of real authentication as long as the interface matches.

A rather important concept surrounding the creation of test doubles is fidelity, that is how closely the behavior of a fake matches the behavior of the real implementation. The higher the fidelity, the better, that means the fakes resemble more closely to production codes and in turn, we can rely on them to catch bugs in the event of breakages.

However, one downside of fakes is that they can be difficult to create and burdensome to maintain.

Stubs and Spies

Other techniques are stub and spy. By definition, stubbing is a process of adding behavior to a function that otherwise does not yet exist. Though, can also be used to replace an existing behavior in order to avoid having to deal with dependency.

Spies on the other hand are just stubs but they keep track of invocation such that you can verify how many times they're being called.

In Jest, stubs and spies are the same thing, they can be created with jest.spyOn(),

interface Counter {
  count: number;
  getCount: () => number;
  getCountText: () => string;
}

const myCounter: Counter = {
  count: 0,
  getCount: function () {
    return this.count;
  },
  getCountText: function() {
    const count = this.getCount();
    if (count > 10) {
      return 'More than 10';
    } else {
      return count.toString();
    }
  }
};

jest.spyOn(myCounter, 'getCount').mockReturnValue(20);
expect(myCounter.getCountText()).toEqual('More than 10');

In the example above, we stub a behavior on getCount method such that it will always return a value 20 no matter what.

Stubs are appropriate when there's a need to simulate a wide variety of return values that might not be possible should we use real implementation or fakes.

Additionally, since Jest treats stub and spy object as the same thing, that means we can verify that the object is indeed being invoked.

  expect(mockCounter.getCount).toHaveBeenCalled(); // ✅

Because stubbing is so easy to apply, it can be tempting to treat it as easy patch to otherwise non-trivial behaviors. Deviation from real implementation is a real concern if we excessively rely on stubs to customize implementations.

Mocks

You might notice that up until now, what we're doing is simply validating if the "state" is correct given conditions. In other words, we're doing a state verification, a test that verifies whether the exercised method worked correctly by verifying the state of the system under test.

The thing is, the system under tests may or may not be stateful, in which case we need to employ behavior verification testing, a test that verifies invocation of a certain method. And this is where mocks came into play.

Mocks are pre-programmed objects with the ability to observe invocations. During test, the mocked object is used instead of the real object, this is a good way to ensure that side-effects do not happen. And more, we can set assertions such that the test should fail if a function isn't called at all, called with the wrong arguments, or called too many times.

Suppose we have an object called analytics that contains a number of methods that look like this,

// analytics.ts
const analytics = {
  sendEvent: function(eventName: string) {
    // send even to analytics dashboard;
  },
  sendButtonClickEvent: function() {
    this.sendEvent('button-click');
  },
  sendInitEvent: function() {
    this.sendEvent('init');
  }
};

export default analytics;

We probably don't want to send an actual event to the analytics dashboard during tests, but we do need to make sure that they're called.

To solve this, we can mock the analytics module,

jest.mock('./analytics');

test('test analytics module', () => {
  const analytics = require('./analytics').default;
  expect(analytics.sendEvent._isMockFunction).toEqual(true);   // ✅
  expect(analytics.sendButtonClickEvent._isMockFunction).toEqual(true);   // ✅
  expect(analytics.sendInitEvent._isMockFunction).toEqual(true);   // ✅
});

jest.mock('./analytics') in this case is an equivalent to

const analytics = {
  default: {
    sendEvent: jest.fn(),
    sendButtonClickEvent: jest.fn().
    sendInitEvent: jest.fn()
  }
}

export default analytics;

jest.fn() is a handy function that will erase the current behavior of a method and replace it with a mock object. With this, we can safely invoke analytics.sendEvent() for testing purposes and don't have to worry about side effects.

We can then perform a thorough assertions like this,

analytics.sendEvent('button-click');
analytics.sendEvent('init');

expect(analytics.sendEvent).toHaveBeenCalledTimes(2);   // ✅
expect(analytics.sendEvent).toHaveBeenCalledWith('button-click');   // ✅
expect(analytics.sendEvent).toHaveBeenCalledWith('init');   // ✅

One downside of this kind of testing is that it utilizes implementation details of the system under test. We are exposing to the test that the system under test calls this exact function.

In this article, Kent C. Dodds puts it well, testing implementation details are bad because of two reasons:

Test can break if we refactor application codes. False negatives
Test may not fail if we break application code. False positive

Both cases suggest that the test knows too much of the inner detail of the system under test.

State Verification VS Behavior Verification

One thing that I asked myself a lot during test was that should I use a mock or a stub?

It turns out, the answer to this question depends on whether it's more appropriate to perform a state verification rather than behavior verification.

In the article Mocks Aren't Stubs by Martin Fowler, this decision almost always depends on context. Are we talking about easy collaboration or a rather awkward one?

If the collaboration is easy, for example between the Order class and Warehouse class, we are more likely to be able to use real objects or stubs and perform a state verification. If it's an awkward collaboration, such as collaboration between Order class and MailService class, we are likely to use mock and perform a behavior verification.

Another factor to consider is how close both of these methods of testing resembles the actual working codes. The primary issue with behavior verification is that we can't be sure that the system under test is working properly, we can only validate that certain function is called as expected. For example, if database.save(payload) function is called, we can only assume that the item will be saved to the database. While with state verification, we can actually perform a query to the database to verify that the item indeed exists.

Of course, in the end, we need to measure the tradeoffs between the two decisions.

Conclusion

One thing I learned about software testing is that different testing frameworks have different takes on test doubles creation. In jest, test double creation is limited to jest.mock() and jest.spyOn(), stub and spy are treated as the same thing, and you can use mock and stub interchangeably. While in sinon, there are sinon.stub(), sinon.fake(), sinon.mock(), and sinon.spy().

Test doubles are extremely valuable in helping engineers write comprehensive test suites that run fast. However, misusing them can result in a maintenance nightmare. That's why it's important for engineers to understand the ups and downs of each kind of test double. Oftentimes, engineers need to make trade-offs regarding which technique to use.

CSS Container Query: A Media Query on Steroids

Frendy Guo — Sun, 12 Dec 2021 07:19:25 +0000

One of the most requested web features finally sees the light of day. As of today, container query is on its first public working draft — meaning this feature has proven to be essential and deemed possible to be included in future versions.

You can even try it now on Google Chrome. Go to chrome://flags/#enable-container-queries on your Chrome browser, set it to enabled and you’re good to go.

Container Query

A new CSS query that offers a possibility for a descendant element to apply styling rules based on the container.

While media query applies specific styling based on viewport and media preferences, container query takes it a step further by allowing the contained element to target the container elements. This offers more granular controls to the contained element.

Here's simple usage of container query,

.card {
  background-color: red;
}

.container {
  container-type: inline-size;
}

@container (min-width: 300px) {
  .card {
    background-color: blue;
  }
}

This basically tells the browser to apply style background-color: blue if the container is at least 300px wide.

The syntaxes are fairly simple and quite similar to that of media query. Container query comes with three extra properties and a rule.

First, we have container-type, this property is used to establish the element as query container, this will allow the child component to query against it.

.foo {
  container-type: none | style | state | size | inline-size | block-size;
}

Second, container-name sets a name to the container for further filtering. Sometimes we might not want to target the nearest ancestor container, this property serves as an escape hatch.

.foo {
  container-name: my-container;
}

And finally, container is used as a shorthand property that can be used to set both container-type and container-name in a single declaration.

.foo {
  container: inline-size / my-container;
}

To target the container, we use @container to specify the rule to target the nearest containment context.

// Applies if the nearest query container is at least 700px wide
@container (min-width: 700px) {}

// Applies if the nearest query container has an inline-size of more than 100px
@container (inline-size > 100px) {}

// Applies if the nearest query container named `my-component` is at least 700px wide
@container my-component (min-width: 700px) {}

This is very exciting because the child element can be made aware of its surroundings and can decide for itself how to react.

A Highly Modular Component

Consider a Card component, a fairly common piece of an element that you've probably seen before. This component has the following attributes: A thumbnail, a headline, a description, and some tags.

We want the component to adapt to different screen sizes. On the smallest viewport, the thumbnail and details are stacked vertically. On a slightly larger viewport, the thumbnail will reside on the left. And finally, on the largest viewport, our content will sit on top of the thumbnail.

Let's start with the HTML codes,

<div class="card">
  <div class="card-thumbnail">
    <div class="card-thumbnail-wrapper"></div>
  </div>
  <div class="card-detail">
    <div class="card-tag">
      <div class="card-tag-item">Technology</div>
      <div class="card-tag-item">Entertainment</div>
    </div>
    <h3 class="card-title">Headlines: The Good, The Bad, and The Ugly</h3>
    <div class="card-description">
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque aliquam eros justo, sit amet sollicitudin ligula aliquet vel. Sed a neque turpis.
    </div>
  </div>
</div>

And the CSS,

.card {
  background-color: #ffffff;
  border-radius: 8px;
  box-shadow: 0 2px 6px rgba(0, 0, 0, .5);
}

.card-thumbnail {
  flex: 0 0 auto;
  background-color: #DFDFDF;
  border-top-left-radius: 4px;
  border-top-right-radius: 4px;
  overflow: hidden;
}

.card-thumbnail-wrapper {
  padding-bottom: 56.25%;
  position: relative;
  background-image: url('./mountain.jpeg');
  background-size: cover;
  background-position: center;
}

.card-detail {
  padding: 12px;
}

.card-title {
  font-size: 15px;
  line-height: 19px;
  font-weight: 600;
  margin: 8px 0 0 0;
}

.card-description {
  font-size: 13px;
  line-height: 17.2px;
  margin-top: 8px;
}

.card-tag {
  display: flex;
  justify-content: flex-start;
  gap: 12px;
}

.card-tag-item {
  color: #ffffff;
  background-color: #333;
  padding: 4px 6px;
  border-radius: 6px;
  font-size: 12px;
  font-weight: 600;
}

So far so good. Our card looks good on a smaller screen, exactly as we planned.

On a slightly larger viewport, instead of media query, we will utilize container query to help us deal with the transformation.

@container (min-width: 321px) {
  .card {
    display: flex;
  }

  .card-thumbnail {
    width: 150px;
    border-top-right-radius: 0;
    border-bottom-left-radius: 4px;
  }

  .card-thumbnail-wrapper {
    padding-bottom: 100%;
  }

  .card-detail {
    padding: 16px 12px;
  }
}

We can use display: flex; to stack the content horizontally, and we also added some minor adjustments to the thumbnail and details to ensure it still looks good.

And finally, on the largest viewport we updated our thumbnail to fill up the spaces, add some dark overlay on top of the thumbnail with background: linear-gradient(....);, we also set our .card-detail to position: absolute; and changed the color of our headline and description to #ffffff.

@container (min-width: 561px) {
  .card {
    position: relative;
  }

  .card-thumbnail {
    width: 100%;
  }

  .card-thumbnail-wrapper {
    padding-bottom: 45%;
  }

  .card-thumbnail-wrapper::after {
    content: '';
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: linear-gradient(to bottom, rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.55));
  }

  .card-detail {
    padding: 28px 20px;
    position: absolute;
    bottom: 0;
    left: 0;
  }

  .card-title {
    font-size: 20px;
    color: #ffffff;
  }

  .card-description {
    font-size: 15px;
    color: #ffffff;
  }
}

Our card now looks like this if the container is at least 560px wide.

Awesome, our card component looks great on different viewports. But more importantly, what makes container query excel is that we can reuse the same component in more complex layouts.

I created an example to demonstrate the prowess of container query,

<div class="grid-4"> 
  <div>
    <div class="card">...</div>
  </div>
  <div>
    <div class="card">...</div>
  </div>
  <div>
    <div class="card">...</div>
  </div>
  <div>
    <div class="card">...</div>
  </div>
</div>
<div class="grid-2">
  <div>
    <div class="card">...</div>
  </div>
  <div>
    <div class="card">...</div>
  </div>
</div>
<div class="grid-1">
  <div>
    <div class="card">...</div>
  </div>
</div>

.grid-4,
.grid-2,
.grid-1 {
  display: grid;
  column-gap: 24px;
  margin-top: 24px;
}

.grid-4 > div,
.grid-2 > div,
.grid-1 > div {
  container-type:  inline-size; 
}

.grid-4 {
  grid-template-columns: 1fr 1fr 1fr 1fr;
}

.grid-2 {
  grid-template-columns: 1fr 1fr;
}

.grid-1 {
  grid-template-columns: 1fr;
}

The same components, under the same viewport, adapt to different layouts gracefully. Without container query, you would need a workaround to make this work, perhaps by adding a class name to differentiate the selector or involving Javascript.

Moreover, depending on global viewport via media query makes our component less modular — in other words, they are much harder to reuse across different layouts.

Size and Other Aspects

We might not always know the dimension ahead of time. But worry not, the container query comes with a number of declarative query types you can use to evaluate against the container.

Container Size Query

The first type, container size query establishes the container to enable query against its size. Possible values of this type are size, inline-size and block-size.

size type establishes the container to be queried against its size in both inline and block axis.

In CSS, inline and block axes refer to the direction in which text flows within a line. For example in the English language, text flows from left to right and top to bottom.

Container set to a size type allows it to be queried upon its width and height. And similarly, inline-size and block-size allows query upon container's width and height respectively.

Container Style Query

The second type is called container style query. This type opens up the possibility to query a container based on its single, specific property.

Container State Query

The third type, container state query establishes the container to enable query against the "current state" of the container such as whether a position: sticky container is "stuck" or that it is currently visible on screen.

Most likely, you would only need size query under normal circumstances but I'm not here to judge 😅. Besides, these are still drafts and might expect **changes in the future. But it does give us a glimpse of what's possible with container query.

Conclusion

The idea of responsive design is fantastic — a user interface so versatile that no matter what device you're on, it always looks elegant and flawless. And thus far, this idea has been mostly achievable with the current state of technology.

I said mostly because there are some cases that just couldn't be solved with media query alone. Often time many smaller tweaks need to be made in order to fit components gracefully into complex layouts. And these are some of the problems container query intend to address.