# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.corets.io/helpers/tag.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.