> For the complete documentation index, see [llms.txt](https://docs.corets.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corets.io/helpers/tag.md).

# Tag

Source code is hosted on [GitHub](https://github.com/corets/tag)

{% tabs %}
{% tab title="yarn" %}

```bash
yarn add @corets/tag
```

{% endtab %}

{% tab title="npm" %}

```bash
npm install --save @corets/tag
```

{% endtab %}
{% endtabs %}

Type **tagging,** also known as **branding**, is a common practice in advanced TypeScript setups. The main purpose of this approach is to make certain primitive types more predictable. Using branded types leads to a better traceability of data in the project and encourages developers to be more aware when working with critical, primitive data.

## Quick Start <a href="#quick-start" id="quick-start"></a>

Let's have a look at this example below:

```typescript
type UUID = string

type User = { id: UUID }
```

We have created a type alias `UUID` that is used on the type `User`. Right now, any `string` value is a valid `UUID`:

```typescript
const user: User = { id: "some-uuid" }
```

This is very implicit, not traceable, and is not very safe since you pay less attention to what is passed around, since everything is just a `string`.

What if we could make this more explicit?

```typescript
import { Tag } from "@corets/tag"

type UUID = Tag<string, "uuid">

type User = {
    id: UUID
}

// this will not work since string is not assignable to UUID
const user1: User = { id: "some-uuid" }

// exlicitly cast it to UUID
const user2: User = { id: "some-uuid" as UUID }
```

Now we are using a branded `string` instead of plain `string`. You can not assign a plain `string` to a `UUID` anymore, if you do so, you have to cast it explicitly. Now you also have full traceability on where `UUID`s are used in the project.

## Tag\<type, alias> <a href="#tagtype-alias" id="tagtype-alias"></a>

Creates a branded type for any primitive value:

```typescript
import { Tag } from "@corets/tag"

const Email = Tag<string, "email">

// this will work
const email2: Email = "foo@bar.com" as Email

// this will not work
const email1: Email = "foo@bar.com"
```

{% hint style="info" %}
You get full traceability of where branded types are used in your project, since you always have to cast a primitive value to that specific type.
{% endhint %}