Currently, all of the different parameters we can pass to our hook is getting hard to read:

export const usePleaseStay = (
  titles: string[],
  animationType: AnimationType,
  faviconLinks: string[],
  interval: number,
  shouldAlwaysPlay: boolean
) => {
  // ...
};

It's a long list of parameters, and when calling the hook, it's easy to get confused about which one is which. Some users may wonder if there is a specific reasoning behind their order. We also could have make a few of the parameters optional and provide reasonable default values. Instead of this long list of function parameters, let's create a type for these parameters along with default values. First create a new folder under 

import { AnimationType } from "../enums/AnimationType";

export type UsePleaseStayOptions = {
  titles: string[];
  animationType?: AnimationType;
  faviconLinks?: string[];
  interval?: number;
  shouldAlwaysPlay?: boolean;
};

This type removes the suggestion previously that there was a sort of order of the parameters, which for our hook is not the case. While 

 required, it is still only typed as an array of strings, and in the JavaScript world, an empty array, i.e. 

 would still be valid, and would break our hook by means of 

 if passed. Let's use a powerful utility type to ensure that the titles array has at least one. We can create another 

 under the types folder, which we'll call 

This type simply enforces that for a given type 

, that the array of that type has at least one item:

export type ArrayOfOneOrMore<T> = {
  0: T;
} & Array<T>;

import { AnimationType } from "../enums/AnimationType";
import { ArrayOfOneOrMore } from "./ArrayOfOneOrMore";

export type UsePleaseStayOptions = {
  titles: ArrayOfOneOrMore<string>;
  animationType?: AnimationType;
  faviconLinks?: string[];
  interval?: number;
  shouldAlwaysPlay?: boolean;
};

 parameter. It can remain optional, but it really only makes sense if it contains at least two entries. A single entry array wouldn't actually lead to any toggling of favicons. Therefore we can make another utility type 

export type ArrayOfTwoOrMore<T> = {
  0: T;
  1: T;
} & Array<T>;

import { AnimationType } from "../enums/AnimationType";
import { ArrayOfOneOrMore } from "./ArrayOfOneOrMore";
import { ArrayOfTwoOrMore } from "./ArrayOfTwoOrMore";

export type UsePleaseStayOptions = {
  titles: ArrayOfOneOrMore<string>;
  animationType?: ArrayOfTwoOrMore<string>;
  faviconLinks?: string[];
  interval?: number;
  shouldAlwaysPlay?: boolean;
};

, we should import this type and use it to type our hook parameters:

// ...
import { UsePleaseStayOptions } from "./../types/UsePleaseStayOptions";
// ...

export const usePleaseStay = ({
  titles,
  animationType,
  faviconLinks,
  interval,
  shouldAlwaysPlay,
}: UsePleaseStayOptions) => {
  // ...
};

---
title: Use Custom Types to Type the Hook Parameters
code: https://gitlab.com/fullstackio/books/react-use-please-stay-with-react-and-typescript/-/blob/production/course/code/lesson-13
isPublicLesson: true
useMdx: true
privateVideoUrl: https://stream.mux.com/kk9KbFrdwR8bYJzBsPJ7TT4iTjoPudjQho3ijIx8oro.m3u8
---

Currently, all of the different parameters you can pass to the hook are getting hard to read:

```ts
export const usePleaseStay = (
  titles: string[],
  animationType: AnimationType,
  faviconLinks: string[],
  interval: number,
  shouldAlwaysPlay: boolean
) => {
  // ...
};
```

It's a long list of parameters, and when calling the hook, it's easy to get confused about which one is which. Some users may wonder if there is a specific reasoning behind their order. You also could have make a few of the parameters optional and provide reasonable default values. Instead of this long list of function parameters, create a type for these parameters along with default values. First create a new folder under `src/` called `types/`:

```shell
mkdir src/types
```

Then create a new file called `UsePleaseStayOptions.ts` in that folder:

```shell
touch src/types/UsePleaseStayOptions.ts
```

Now add the following:

```ts
import { AnimationType } from "../enums/AnimationType";

export type UsePleaseStayOptions = {
  titles: string[];
  animationType?: AnimationType;
  faviconLinks?: string[];
  interval?: number;
  shouldAlwaysPlay?: boolean;
};
```

This type removes the suggestion previously that there was a sort of order of the parameters, which for this hook is not the case. While `titles` _is_ required, it is still only typed as an array of strings, and in the JavaScript world, an empty array, i.e. `[]` would still be valid, and would break the hook by means of `useTitleChangeEffect` if passed. You'll use a powerful utility type to ensure that the titles array has at least one. You can create another `type` under the types folder, which you'll call `ArrayOfOneOrMore.ts`

```shell
touch src/types/ArrayOfOneOrMore.ts
```

This type simply enforces that for a given type `T`, that the array of that type has at least one item:

```ts
export type ArrayOfOneOrMore<T> = {
  0: T;
} & Array<T>;
```

Update the `UsePleaseStayOptions` type to use this new type:

```ts
import { AnimationType } from "../enums/AnimationType";
import { ArrayOfOneOrMore } from "./ArrayOfOneOrMore";

export type UsePleaseStayOptions = {
  titles: ArrayOfOneOrMore<string>;
  animationType?: AnimationType;
  faviconLinks?: string[];
  interval?: number;
  shouldAlwaysPlay?: boolean;
};
```

A similar typing is also true for the `faviconLinks` parameter. It can remain optional, but it really only makes sense if it contains at least two entries. A single entry array wouldn't actually lead to any toggling of favicons. Therefore you can make another utility type `ArrayOfTwoOrMore`:

```ts
export type ArrayOfTwoOrMore<T> = {
  0: T;
  1: T;
} & Array<T>;
```

And you can add this to `UsePleaseStayOptions`:

```ts
import { AnimationType } from "../enums/AnimationType";
import { ArrayOfOneOrMore } from "./ArrayOfOneOrMore";
import { ArrayOfTwoOrMore } from "./ArrayOfTwoOrMore";

export type UsePleaseStayOptions = {
  titles: ArrayOfOneOrMore<string>;
  animationType?: ArrayOfTwoOrMore<string>;
  faviconLinks?: string[];
  interval?: number;
  shouldAlwaysPlay?: boolean;
};
```

Back in `usePleaseStay.ts`, you should import this type and use it to type the hook parameters:

```ts
// ...
import { UsePleaseStayOptions } from "./../types/UsePleaseStayOptions";
// ...

export const usePleaseStay = ({
  titles,
  animationType,
  faviconLinks,
  interval,
  shouldAlwaysPlay,
}: UsePleaseStayOptions) => {
  // ...
};
```

## Adding Default Values

Other than `titles`, the single required parameter, all the other parameters are optional. You can add default values to these parameters by adding `= <value>` to the end of the parameter. Apply sensible default values to each of the optional properties within the `UsePleaseStayOptions` type:

```ts
export const usePleaseStay = ({
  titles,
  animationType = AnimationType.LOOP,
  faviconLinks = undefined,
  interval = 500,
  shouldAlwaysPlay = false,
}: UsePleaseStayOptions) => {
  // ...
};
```

## Modifications to the Code

Since many of the parameters are now optional, you need to make a small modifications to the code. Mainly, you need to type and check the value of `faviconLinks` in `useFaviconChangeEffect`. First, you can use the `UsePleaseStayOptions` type for typing `faviconLinks`:

```ts
export const useFaviconChangeEffect = (
  faviconLinks: UsePleaseStayOptions['faviconLinks'],
  // ... other parameters
)
```

and you should only run the interval in the case when `faviconLinks` is not undefined:

```ts
useInterval(
  () => {
    if (faviconLinks !== undefined) {
      const nextIndex = faviconIndex + 1;
      nextIndex === faviconLinks.length
        ? setFaviconIndex(0)
        : setFaviconIndex(nextIndex);
    }
  },
  interval,
  shouldIterateFavicons
);
```

and the same guard in the `useEffect` hook:

```ts
useEffect(() => {
  if (faviconLinks !== undefined) {
    faviconRef.current.href = faviconLinks[faviconIndex];
  }
}, [faviconIndex, faviconLinks]);
```

## Documenting the Hook Parameters

With all this work complete, you should document the parameters the hook can accept within the README. Add the following to your README:

```md
## Parameters

Parameters for `usePleaseStay` are passed via an object of [type `UsePleaseStayOptions` (click me!)](./src/types/UsePleaseStayOptions.ts).

| Name               | Type                       | Default Value                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------ | -------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `titles`           | `ArrayOfOneOrMore<string>` | **Required, an array of strings with at least one value** | The titles to iterate through. Note that with certain `AnimationType` only the first title is taken.                                                                                                                                                                                                                                                                                                                               |
| `animationType`    | `AnimationType`            | `AnimationType.LOOP`                                      | The animation type on the title. There are three types:<br/>- `AnimationType.LOOP`: each title in the `titles` is iterated sequentially<br/>- `AnimationType.CASCADE:` Only the first title in the `titles` array is taken, and the title is modified by adding one letter at a time<br/>- AnimationType.MARQUEE - only the first title in the `titles` array is taken, and the title animates across the tab in a marquee fashion |
| `faviconLinks`     | `ArrayOfTwoOrMore<string>` | `undefined`                                               | The desired favicon links to animate through                                                                                                                                                                                                                                                                                                                                                                                       |
| `interval`         | `number`                   | `500`                                                     | The rate in milliseconds at which the title and favicon change occurs                                                                                                                                                                                                                                                                                                                                                              |
| `shouldAlwaysPlay` | `boolean`                  | `false`                                                   | The rate in milliseconds at which the title and favicon change occurs                                                                                                                                                                                                                                                                                                                                                              |
```

Chris Frewin

Use Custom Types to Type the Hook Parameters

Currently, the way we can pass all these different parameters to our hook is

It's a long list of parameters, and it's easy to get confused on which one is

Some users may even wonder if there's a specific reasoning behind their order.

We also know throughout our implementation we probably could have made some of

these parameters optional and provided sensible defaults for each of them.

So let's create a type for these parameters, and then we'll be able to add

default values for some of the optional ones.

First, we'll create a folder under SRC called types.

And I'm going to call this type use, please stay options. And so we'll export

And we know we have our titles, which is a string array.

We have our animation type, which we can make optional, and its type is

We have our BayVyCon links, which is also optional, and a string array.

We have our interval, which is also optional, and is a number, and we have

Now this type will remove the suggestion that there's a sort of order to the

parameters, which of course for our hook is not the case.

And there's a few minor optimizations we can make to this type.

We notice that titles is required, and there's a sort of loophole in the typ

ings here in that I could pass an empty array, and both TypeScript and

JavaScript would still be happy with that.

And as we know, in some of our use title change effect logics, if the array is

empty, that will end up crashing our hook.

So we're going to make a utility type to guard against that. Essentially, this

utility type will require that the string array past the titles has at least

So still in the types folder, I'm going to create a new type called array of

And that's export type array of one or more, and this will accept a generic

And we just want that first entry to be the generic type.

And with that first entry being the generic type desired, we can union that

So back in use, please stay options. We can import that type.

And we'll apply it here to the titles parameter instead of a string array.

We will add a ray of one or more, and the generic type here is string.

Now, the same is also true for the fav icon links, even though it's optional.

If it is passed, we should also guard against the empty case.

But we should also guard against a single value case. That is, if we look in

our fav icon change effect here, if fav icon links array with just one entry

It just wouldn't do anything. And so I think it's a fair type guard to require

that the user pass at least two fav icon links.

Otherwise, the toggle effect that they expect won't happen.

So very similar to array of one or more, I'm going to copy this and create a

You can rename the type here and just add the second value to also be that

So in the use, please stay options, we will modify this to be the array of two

And type string. And in use, please stay, we can import this type and apply it

So the first thing I'll do is strip off all the types.

And we're just going to wrap this whole thing in brackets.

And we can type it according to use, please stay options.

And as we said, the only required parameter here is titles.

And with this type of notation, it's quite easy to provide default values for

So for animation type, I'll take animation type loop.

And for the fav icon links, this one will be undefined.

Our interval will take 500 milliseconds that we saw in some of the previous

And we'll do should always play set to false.

So this keeps the original functionality that we implemented, which is the

animations will only run when focus is lost.

So with these default values set, there's only one small change we need to make

And that is to account for this undefined fav icon links.

So if we look in use fav icon change effect, the first thing we'll do here is

ensure that the type is that of the use, please stay options.

And of course, we don't want the full type, but we just want the type of the

And so we know this now is either undefined when it's not passed at all.

But if it is defined, it has at least two elements.

And to guard against the case that fav icon links is undefined, we're just

going to wrap the whole use interval function with if fav icon links.

Then we will run the increment logic here.

And we also should add the same guard down in the use effect.

Just to ensure that we're not going to access fav icon links or try to access

And we should also add it to our dependency array.

With the effort we've put into our custom type for the parameters, it's a good

point in time that we document all of these parameters.

And a good place to document this is in the read me.

And I'm not going to bore you with typing out the entire documentation.

But essentially what it is is a markdown table with the name, the type, the

Of each of the parameters that we have in our use please stay options.

And I always find it nice in the GitHub read me when people link directly to

And in GitHub, you're allowed to link relatively to the read me.

And so the use please stay options source file is of course the file we've just

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Masterclasses

Tutorials

Fullstack React with TypeScript