Forem: Luis Gustavo Macedo

Typescript - Union types e type guards

Luis Gustavo Macedo — Mon, 17 Jul 2023 14:45:16 +0000

Salve galera!

Hoje quero compartilhar mais um pouco sobre typescript, especificamente algumas técnicas utilizando Union Types e type guards.

Vou mostrar como você pode melhorar seu código typescript pra deixá-lo mais legível, e bem documentado.

1 - Union types

Um Union types é um tipo formado por outros tipos, onde pode assumir qualquer um daqueles possíveis valores.

Alguns exemplos

type NumberOrString = number | string;

type Status = "idle" | "loading" | "success" | "failure"

// React useState, can receive a value or a function as parameter to serve as initial value. 
// https://github.com/DefinitelyTyped/DefinitelyTyped/blob/a03856975a17eba524739676affbf70ac4078176/types/react/v17/index.d.ts#L920
function useState<S>(initialState: S | (() => S)): [S, Dispatch<SetStateAction<S>>];

2 - Typeguard

Já o typeguard é uma forma de dizer para o typescript, por meio de algum fluxo de controle if/else, loops, ternários e etc, refinar - chamamos de narrow - um determinado tipo para um tipo mais específico em algum escopo definido.

Dessa forma, conseguimos inferir que em algum ponto do código, um tipo pode assumir um tipo específico.

Pra quem quiser ler mais sobre narrowing e typeguards, lá tem bastante exemplo e uma explicação completa.

Podemos fazer o narrowing apenas com operações javascript.

// using switch
type Order = OrderCompleted | OrderProcessing | OrderReady;

function processOrder(order: Order) {
  switch (order.status) {
    case "completed": {
      console.log(order.deliveryAt) // Narrow to OrderCompleted 
      return;
    }
    case "processing": {
      console.log(order.expectDeliveryAt) // Narrow to OrderProcessing 
      return;
    }
    case "ready": {
      console.log(order.productId) // Narrow to OrderReady 
    }
  }
}

TS Playground

// using in operator
interface Dog {
    walk: () => void;
}

interface Fish {
    swim: () => void;
}

type Animal = Dog | Fish;

function move(animal: Animal) {
    if ("walk" in animal) {
        animal.walk(); // Narrow to Dog
        return;
    }

    animal.swim(); // Narrow to Fish
}


// using typeof
function promise(callback?: () => void) {
    // ...
    if (typeof callback !== "undefined") {
        callback(); // So in this scope you ensure that function exists
    }
}

Ts Playground

Tudo que fizemos até agora foi apartir do fluxo do código usar operações javascript para ajudar o typescript a fazer o narrowing e inferir tipos mais específicos.

Agora, se quisermos fazer nossas próprias validações, sem usar explicitamente operações javascript como typeof, in, instanceof e outros, no fluxo do código, mas sim encapsular toda a lógica de validação em uma função, como um parser ou algo do tipo. Pra isso podemos usar o type predicates do typescript.

3 - Type Predicates

Um exemplo muito comum é quando fazemos uma chamada pra API e apenas inferimos o tipo do retorno, mas o que garante pra gente que a API mandou o objeto correto?

O problema

interface User {
    name: string;
    email: string;
}

declare const api: <T>(endPoint: string) => T

function getUser() {
    const user = api<User>("/user"); // We assume that the response payload actually sent the object with the type strictly equal to User

    console.log(user.email); 
    console.log(user.name);
}

Podemos fazer uma função para garantir que o objeto user é de fato do tipo User.

interface User {
    name: string;
    email: string;
}

function isUser(input: unknown): input is User  {
    return (
        typeof input === "object" && 
        !!input &&
        "name" in input &&
        "email" in input
    ) 
}

declare const api: <T>(endPoint: string) => T

function getUser() {
    const user = api("/user"); // We can pass the User as a generic here, however we have to remember to do the validation

    if (isUser(user)) { // With this type guard, we can be sure that the API response actually returned a User. 
        console.log(user.email); 
        console.log(user.name);
        return;
    }
}

Ts Playground

Porém ainda tem um problema aqui, veja no playground.

Suponha que estamos no final da sprint, e então surge uma urgência e temos que introduzir mais um campo no tipo User, por exemplo, o campo avatar. Nossa função isUser não vai acusar nenhum erro por não estarmos verificando o campo avatar.

Como a sprint está acabando e fizemos a alteração as pressas, esquecemos de alterar a função e nosso isUser não está funcional, não cumpre com o que deveria, por que não valida se de fato o objeto é um User. Então, bummm introduzimos um possível bug em produção.

Podemos resolver isso mudando um pouco nossa função para ser um parser de fato, e deixar ela mais completa validando também o tipo de cada propriedade

function parseUser(input: unknown): User | null {
    const isObject = typeof input === "object" && input
    if (!isObject) return null;

    const hasUserProperties = 
        "name" in input &&
        "email" in input

    if (!hasUserProperties) return null;

    const { email, name } = input;

    if (typeof email !== "string") return null;
    if (typeof name !== "string") return null;

    return { email, name } // Property 'avatar' is missing in type '{ email: string; name: string; }' but required in type 'User'.(2741)
}

function isUser(input: unknown): input is User {
    return input !== null
}

Veja no playground, agora se novas propriedades forem adicionadas nossa função irá acusar erro.

Já temos algumas ótimas ferramentas pra fazer todo esse parser, como o zod

4 - Extract Utility

Pra finalizar, quero mostrar um utilitário muito poderoso que o typescript oferece quando trabalhamos com union types.

Por exemplo, se o union for de uma biblioteca externa, e não temos acesso a cada possível valor de forma isolada. Podemos inferir o tipo específico usando o Extract.

O Extract recebe dois genéricos, o primeiro é o Union de fato e o segundo apenas a união que vai ser extraída.

type Payment = 
    | { status: "pending" }
    | { status: "paid", paidAt: string }
    | { status: "canceled", canceledAt: string } 

type PendingPayment = Extract<Payment, { status: "pending" }>; // { status: "pending" }
type PaidPayment = Extract<Payment, { status: "paid" }>; // { status: "paid", paidAt: string }
type CanceledPayment = Extract<Payment, { status: "canceled" }>; // { status: "canceled", canceledAt: string } 

type Shape = {
  kind: "square";
  size: number;
} | {
  kind: "circle";
  radius: number;
};

type Square = Extract<Shape, { status: "square" }>; // { kind: "square"; size: number; } 
type Circle = Extract<Shape, { status: "circle" }>; // { kind: "circle"; radius: number; }

TS Playground

É isso, acho que assim da pra deixar o código mais explícito, legível e bem documentado.

Referências:

A Golang bot to count down the best day of your life - the holidays

Luis Gustavo Macedo — Thu, 06 Jul 2023 18:14:16 +0000

Returning with my desire to share knowledge and experience, today i will show a very cool project that i built in the last year.

At the time, I was in the middle of my degree. Although I liked the university and thought that academia is very important for the education of a great software developer (but not mandatory), the holidays are a time that every university student looks anxiously.

The Idea 💡

Then, at the time as I already my studies in Go, and I have a idea, why not make a bot for twitter?🤔 To learn more about golang and make a cool project.

A bot that makes a tweet every day telling how many days are left until college holiday, for me and people at my university accompany.

Repository of project -> https://github.com/Luisgustavom1/go-twitter-bot

Today that's what I want to show, I'll show the simple code of bot and how I built the infra in AWS to automate this process, obviously using the free tier🤑.

Before start I have divided it into 4 main steps 📑:

Create a main function that must receive a date and return how many days are left until this date.
Connect with twitter to make a tweet.
Configure the function in AWS Lambda.
Give a way of execute lambda function every day.

1. The function

The code of this feature is very simple.

I have a function to format date and another to subtract the date.

package main

import (
    "log"
    "math"
    "time"
)

type DaysRemaining int

func main() {
    VACATION_DATE := "2023/06/29 23:00:00 -03"

    vacationDateFormatted, err := getVacationDateFormatted(VACATION_DATE)
    if err != nil {
        log.Fatal(err)
    }
    daysToVacation := getDaysRemaining(vacationDateFormatted)

    log.Println("tweet", daysToVacation)
}

func getVacationDateFormatted(date string) (time.Time, error) {
    const shortFormat = "2006/01/02 15:04:05 -07"
    // Format date to this format and timezone 👆👆 
    dateParsed, err := time.Parse(shortFormat, date)

    if err != nil {
        return dateParsed, err
    }

    return dateParsed, nil
}

func getDaysRemaining(date time.Time) DaysRemaining {
    today := time.Now()
    duration := date.Sub(today)
    // Subtract today from vacation date 
    return DaysRemaining(math.Ceil(duration.Hours() / 24))
}

The main logic is basically that, in another post we can explore more about golang and its powers, but today i just want to give an overview of the code.

2. Connect with twitter

At the time I used this client library to abstract the twitter API, but unfortunately it is deprecated😭

So today maybe it is not the best option. You can venture into twitter api.

In this step I had to generate api keys and access tokens. Every time I get to this part to integrate with third party, I get lost where get this secrets, so here are the ones from twitter api key and access token.

package main

import (
    "log"
    "math"
    "time"
    "os"

    "github.com/dghubble/go-twitter/twitter"
    "github.com/dghubble/oauth1"
)

func main() {
    //...
    // Initial config to oauth 1.0a
    config := oauth1.NewConfig(
        os.Getenv("API_KEY"),
        os.Getenv("API_KEY_SECRET"),
    )
    token := oauth1.NewToken(
        os.Getenv("ACCESS_TOKEN"),
        os.Getenv("ACCESS_TOKEN_SECRET"),
    )

    // Create a http client with oauth 1.0a method
    httpClient := config.Client(oauth1.NoContext, token)

    // Create the client to access twitter api methods(endpoints)
    client := twitter.NewClient(httpClient)

    //...

    daysToVacation := getDaysRemaining(vacationDateFormatted)
    messageToTweet, err := generateMessageToTweet(daysToVacation)
    if err != nil {
        log.Fatal(err)
    }

    // Method to publish a tweet
    client.Statuses.Update(messageToTweet, nil)
}

3. Create the Lambda Function

At the time I only knew the concept about lambda functions so it would be one more tech that I would learn with this simple project.

Let's create lambda function.

Choose Author from scratch.
Put the name of your bot.
Select the language and architecture.

Now, to work with Lambda using go, we have to change the code a little bit and use this official aws tool.

So we import the package, rename main function to Handler and create a new main that will execute the .Start() method, of aws tool.

The Handler function is method that manipulate the events. The main function is required, is the entry point where aws lambda will run our code.

package main

import (
    // ...
    // Import the package
    "github.com/aws/aws-lambda-go/lambda"
)

type DaysRemaining int

func main() {
    // The `main` should start the Handler function
    lambda.Start(Handler)
}

// Out function that contains the logic
func Handler() {
    VACATION_DATE := "2023/06/29 23:00:00 -03"

    config := oauth1.NewConfig(
        os.Getenv("API_KEY"),
        os.Getenv("API_KEY_SECRET"),
    )
    // ...
}

If you want developing something more complexity, with multiply events and features, you can access the event name and work with context in Handler function, see more.

After finishing the code, don't forget of upload the code to AWS lambda, either by uploading the .zip file or by configuring an s3 bucket, and add the twitter keys in the environment variables (Configuration > Environment variables).

4. Running every day

Someone once told me that

"Developers are the laziest, because they want to automate everything"

Sice obviously I won't execute manually the lambda every day, we can use the AWS CloudWatch Events to trigger the function at the specific time.

Then let's add a trigger

Select EventBridge (CloudWatch Events).
Check Create a new rule.
Check Schedule Expression.
Put the cron expressions.

For my bot I use this cron cron(00 09 ? * * *), It will run every day at 09:00 UTC, that is, 06:00 in GTM-3.

If when creating your lambda function, you kept these configs checked (the default configs): Permissions > Change default execution role > Create a new role with basic Lambda permissions. You won't have to worry with the IAM role for lambda access the cloud watch, the AWS already create the role for you, lambda permissions.

That's it, see the bot perfil in twitter.

Hope you are enjoying.

Follow me on social networks:

Typescript - Type System

Luis Gustavo Macedo — Mon, 03 Jul 2023 12:56:10 +0000

Hi guys,

I have always wanted to produce content about programming and technology from some of the subjects I know, so that more people can learn.

So I am getting courage and starting to produce content.

Besides sharing knowledge I also intend to learn a lot from these articles. As I am not a genius and do not know everything, so please correct me, give suggestions, theories and let's make this space a environment for discussion and exchange of experiences and knowledge.

I rolled a lot in the introduction, so let to that is important.

You know typescript?

Do you know how to extract the maximum of typescript?

In this article we will create a type system for the a query builder to study and explore the maximum of the typescript. So will focus on the type and not in the implementation. Final code

What is the query builder?

As this is not the proposal, I asked for the GPT
"A query builder is a software tool or library that allows developers to construct database queries in a more intuitive and efficient way. Instead of writing raw SQL statements, which can be complex and error-prone, a query builder provides a higher-level abstraction that enables users to build queries using a more human-readable and structured syntax."

We will build something like this

const user = await QueryBuilder.database(myDbInstance)
    .from("user")
    .select(["id", "email", "name"])
    .where("id = :id", { id })
    .build();

We will learn and have a little notion about

generics
keyof operator
infer operator and conditional
manipulate strings
mapped and Indexed Access types

#1 Mapping the database and table of query

In this step we will use some of generics.

First we have to type the function which will server as builder, how this function use the design pattern builder, do not forget to return the own function to make this composition .from(...).select(...).where(...)

Using this database shape for tests

interface User {
  id: number;
  name: string;
  email: string;
  password: string;
  updated_at: Date;
}

interface Product {
  id: number;
  name: string;
  description: string;
  price: number;
}

interface Order {
  id: number;
  user_id: number;
  product_id: number;
  quantity: number;
  created_at: Date;
}
// Use  this DB for tests
type DataBaseTest = {
  user: User;
  product: Product;
  order: Order;
}

Init of query builder

declare namespace QueryBuilder {
  function database(db: DataBaseTest): QueryBuilderMethods;
}

type QueryBuilderMethods = {
  from: (table: keyof DataBaseTest) => QueryBuilderMethods,
  build: () => Promise<void>
}

Ts playground

keyof

The keyof takes all the keys of the object and returns the union them.
Then, in this case all keys of DataBaseTest, that is

// "user" | "product" | "order"
type Tables = keyof DataBaseTest;

Dynamic?

But that way our queryBuilder is not dynamic. If we want to use it in another database?

So add a generic to get the database that was selected via params of database() methods.

declare namespace QueryBuilder {
  function database<DB>(db: DB): QueryBuilderMethods<DB>;
}

type QueryBuilderMethods<DB> = {
  from: (table: keyof DB) => QueryBuilderMethods<DB>,
  build: () => Promise<void>
}

Ts playground

The generic will capture the type that was passed in database() method and pass to QueryBuilderMethods for him use as he sees fit.

With this change the build became dynamic, it can receive any database

const myDbInstance = {} as DataBaseTest;

QueryBuilder.database(myDbInstance)
  // "user" | "product" | "order"
  .from("order")
  .build()

const anotherDbInstance = {} as AnotherDatabase;

QueryBuilder.database(anotherDbInstance)
  // "user" | "payment"
  .from("payment")
  .build()

#2 Mapping the all columns of table selected

In this step we'll add the .select() method, that can receive all columns of table, in other words, receive all keys from the table.

How the .select() depends on what was passed on .from(), we have to add one more generic, the Table in question.

type QueryBuilderMethods<
  DB,
  Table extends keyof DB = keyof DB
> = {
  from: (table: Table) => QueryBuilderMethods<DB>,
  select: (s: Array<keyof Table>) => QueryBuilderMethods<DB>,
  build: () => Promise<void>
}

The extends in generic, works like typing for him. The Table can receive the keys of DB and added a default value that is keyof DB
But if you test, ts playground, it won't work yet, why?

That's because we made it too generic. Then we have add more specificity in some points.

type QueryBuilderMethods<
  DB,
  Table extends keyof DB = keyof DB
> = {
  // Here, needs specify the table, not any `key` of `DB`
  from: <T extends Table>(table: T) => QueryBuilderMethods<DB, T>,
  select: (s: Array<keyof DB[Table]>) => QueryBuilderMethods<DB, Table>,
  // Don't forget to always pass the generics to 
  // `QueryBuilderMethods`, in all methods, it will serve for 
  // the next method that is used in the builder
  build: () => Promise<void>
}

We already have that ts playground

#3 `.where()` method

"WHERE user.id = 1"

The idea of this method is receive a string with condition, and a object with the values that will be used in the condition.

The string should follow this pattern "column operator :value"

Let's create a utility to make the where string and add new .where() method

type QueryBuilderMethods<
  DB,
  Table extends keyof DB = keyof DB,
  Columns extends keyof DB[Table] = keyof DB[Table]
> = {
  // ...,
  where: (
    w: MakeWhereString<Columns & string>,
  ) => QueryBuilderMethods<DB, Table>,
  // ...
}

type MakeWhereString<
  Column extends string, 
  Operator extends string = ComparisonOperators, 
  Value extends string = string
> = `${Column} ${Operator} :${Value}`;

type ComparisonOperators = "=" | "<>" | ">=" | "<=";

Beyond utility, i moved keyof DB[Table] to Columns generic for more readability.

Ts playground

The where can only accept one string that has "column_of_table_selected ComparisonOperators :value"

QueryBuilder.database(myDbInstance)
  .from("order")
  .select(["id", "created_at", "quantity"])
  // ERROR: Only receive columns of order table
  .where("field = :id")
  .build()

QueryBuilder.database(myDbInstance)
  .from("order")
  .select(["id", "created_at", "quantity"])
  // ERROR: Only receive one of operators
  .where("id === :id")
  .build()

QueryBuilder.database(myDbInstance)
  .from("order")
  .select(["id", "created_at", "quantity"])
  // ERROR: Must have the ":"
  .where("id = id")
  .build()

See the errors Ts playground

Use template literal types in typescript is very useful, this is a simple approach to use them.

#4 Extract the column of where string

Now we will use infer and conditionalto extract the which column that was specified

Let's make a utility type for this

type ExtractColumnByWhere<Str> = Str extends MakeWhereString<infer C>
  ? C
  : never;

infer basically extracts from within another type structure, some type. Combining with conditional, we can return this type if typescript could infer the type correctly. Read more about infer keyword.

So let's put all this into our structure and make the object with the values using mapped types

type QueryBuilderMethods<
  DB,
  Table extends keyof DB = keyof DB,
  Columns extends keyof DB[Table] = keyof DB[Table],
> = {
  //...
  where: <
    W extends MakeWhereString<Columns & string>,
    V extends ExtractColumnByWhere<W> 
  >(
    w: W,
    v: { [K in V]: DB[Table][V & Columns] }
  ) => QueryBuilderMethods<DB, Table>,
  //...
}

Ts playground

The Mapped types is a way to create new types of objects without repeating yourself, it iterates over the union of keys and creating the new object.

Works like this

type NewObjectKeys = "key" | "key1" | "key3"
type NewObject = { 
  [K in NewObjectKeys]: string
}
// Result in: {
//     key: string;
//     key1: string;
//     key3: string;
// }

Ts playground

#5 Make the `build` return

In the end, we need of the columns selected in the .select() methods, to make the return of our query builder.

Let's make a simple change to capture selected columns from generics

type QueryBuilderMethods<
  DB,
  Table extends keyof DB = keyof DB,
  Columns extends keyof DB[Table] = keyof DB[Table],
  // New Generics, based on the table columns
  ColumnsSelected extends Array<Columns> = Array<Columns>,
> = {
  from: <T extends Table>(table: T) => QueryBuilderMethods<DB, T>,
  // Here should be more specific, not just any columns array, but the columns array that is passed by params
  // and pass this columns again to return of .select() through generics of QueryBuilderMethods
  select: <S extends Array<Columns> = Array<Columns>>(s: S) => QueryBuilderMethods<DB, Table, Columns, S>,
  where: <
    W extends MakeWhereString<Columns & string>,
    V extends ExtractColumnByWhere<W> 
  >(
    w: W,
    v: { [K in V]: DB[Table][V & Columns] }
  // Don't forget of pass the generics to  `QueryBuilderMethods`
  ) => QueryBuilderMethods<DB, Table, Columns, ColumnsSelected>,
  // ...
}

Ts playground

Now that we have the columns selected, can use the Pick and Indexed Access to return object with only keys we selected in .select()

type QueryBuilderMethods<
  DB,
  Table extends keyof DB = keyof DB,
  Columns extends keyof DB[Table] = keyof DB[Table],
  ColumnsSelected extends Array<Columns> = Array<Columns>,
> = {
  // ...,
  build: () => Promise<Pick<DB[Table], ColumnsSelected[number]>>
}

Ts playground
What a workaround this is?
I confess that this is not at all pretty, but I thought this approach was nice.

The Indexed Access we can get a specific type from an indexed type. How ColumnsSelected is a array, we can access all its elements by accessing your number property.

Some examples

const arrayNumbers = [1, 2, 3, 4, 5] as const;
type ArrayNumbers = typeof arrayNumbers

type SpecificNumbers = ArrayNumbers[number] // 1 | 2 | 3 | 4 | 5
type SpecificNumbersIndex = ArrayNumbers[2] // 3

// Works with object
interface User {
  id: number;
  name: string;
  email: string;
  password: string;
  updated_at: Date;
}
type UserEmail = User["email"] // string

Ts playground

That's it. Now we have a query builder fully typed and you probably won't get the column syntax wrong again.

const user = QueryBuilder.database(myDbInstance)
  .from("user")
  .select(["id", "created_at", "email"]) // Only accept the user keys
  .where("email = :email", { email: "email@email.com" }) // String only accept correct user table keys, specific Operators and specific object as second parameter 
  .build()
// Returns ->
// {
//   id: number;
//   email: string;
//   password: string;
// }

Feel free to test the code here
Gist

Conclusion

I hope you understood and left here with some new knowledge.

That's it guys, I want to bring more in-depth content on these subjects and other things from the world of technology.

This month I will create a routine of bringing you some articles every week

Forem: Luis Gustavo Macedo

Typescript - Union types e type guards

1 - Union types

2 - Typeguard

3 - Type Predicates

4 - Extract Utility

A Golang bot to count down the best day of your life - the holidays

The Idea 💡

Before start I have divided it into 4 main steps 📑:

1. The function

2. Connect with twitter

3. Create the Lambda Function

4. Running every day

Typescript - Type System

You know typescript?

Do you know how to extract the maximum of typescript?

What is the query builder?

#1 Mapping the database and table of query

keyof

Dynamic?

#2 Mapping the all columns of table selected

#3 .where() method

#4 Extract the column of where string

#5 Make the build return

Conclusion

#3 `.where()` method

#5 Make the `build` return