When you are working with HarperDB, you can use TypeScript to improve your development experience. This article will show you some best practices to use TypeScript with HarperDB. We’ll talk about folder structures, best practices of code, and how to best set your project to make the most of HarperDB.

Before you start

Make sure you hop into the HarperDB Documentation to know how to install it locally and get started. You can also use the HarperDB Cloud to get started quickly. But I’ll assume you already have your instance running.

Tip: You can check some of my other tutorials here or in this particular community article to know how to set up your infrastructure locally, with Kubernetes, or in the cloud.

This repository is located at the HarperDB Community GitHub. You can clone it and follow along with the article. We’ll be using the cloud version of the database but, in the repository, you’ll find a docker-compose.yml file that you can use to run it locally with docker compose up.

Setting up Node and TypeScript

To use TypeScript you need Node.js installed, be sure to use the latest LTS version. You can check it by running node -v in your terminal. If you don’t have it installed, you can download it here, or use a version manager like asdf, nvm, or even volta.

I’m using version 20.7.0 of Node.js, but you can use any version above 18 at the time of writing this article.

Let’s create a new directory (you can name whatever you want) and, inside it, we’ll run the command npm init -y. This will generate a new package.json file with the default values. Now, let’s install TypeScript as a development dependency by running npm install --save-dev typescript. This will install the latest version of TypeScript in your project.

Tip: You can check the latest version of TypeScript here. I’m using version 5.2.2

We’ll also install the external types for Node.js by running npm install --save-dev @types/node. This will allow us to use the Node.js types in our project.

Lastly, we will add a support package called tsx, which will allow us to develop our application without having to compile it every time we change something. We’ll install it by running npm install --save-dev tsx.

Let’s then bootstrap typescript with npx tsc --init, this will generate a tsconfig.json file with all the definitions TS needs. We’ll need to change some values there, though. So let’s open it, remove all the values and leave it like this:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "NodeNext",
    "outDir": "./dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

We’ll also be using ESModules, so this needs us to change the type key in our package.json file to module. This will allow us to use the import syntax in our code, let’s also add a run script that will allow us to run our compiled code. Our package.json file will be like this:

{
  "name": "hdb-typescript-best-practices",
  "version": "0.0.1",
  "description": "",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node --env-file=.env dist/index.js",
    "start:dev": "NODE_OPTIONS='--loader=tsx' node --env-file=.env src/index.ts"
  },
  "keywords": [],
  "author": "Lucas Santos <hello@lsantos.dev> (https://lsantos.dev/)",
  "license": "GPL-3.0",
  "devDependencies": {
    "@types/node": "^20.7.1",
    "tsx": "^3.13.0",
    "typescript": "^5.2.2"
  }
}

Testing the setup

Now, let’s create a src folder and a index.ts file inside it. This will be our entrypoint for the application. Let’s also add a dist and node_modules folder to our .gitignore file (if you haven’t added already), so we don’t commit the compiled code.

Node.js from version 20.6 up had built-in env file support, so we’ll take advantage of this to store our secrets in a .env file, this is the first best practice:

Best Practice: Never commit secrets to your repository. Use a .env file to store them and add it to your .gitignore file.

Let’s create a .env file and add the following content:

EXAMPLE=Test environment

Now, let’s add the following code to our index.ts file:

export async function main() {
  console.log('Hello world!')
  console.log(process.env.EXAMPLE)
}
await main()

Now run the setup with npm run start:dev, you should see the following output:

$ npm run start:dev
Hello World!
Test environment

This means that everything is correctly set up!

Tip: You can also run the file manually through compilation, to do this, you need to run npx tsc in the root directory, then run node --env-file=.env dist/index.js. This will have the same result. You can even add a build script that will have tsc as a command, so you can run npm run build and then npm run start to run the code.

Setting the environments and the database

Now that we know everything is working, let’s hop to the HarperDB Studio and create our schema. We’ll create a new schema called todo and a table called todo_items. This will be our table that will store the to-do items.

The hash of the table will be the id column:

Harper has a malleable schema, so we don’t need to define all the properties, just the initial hash property, all the others will be added as we create the objects.

Let’s set our environment variables in the .env file:

HDB_HOST=https://your-instance.harperdbcloud.com
HDB_USERNAME=your username
HDB_PASSWORD=your password
HDB_SCHEMA=todo
HDB_TABLE=todo_items

Separating Layers

For our application, we’ll be creating the simple glorious to-do list application. This application will have the following features:

• Create a new to-do item
• List all to-do items
• Mark a to-do item as done
• Delete a to-do item

It’s a simple application, but it will allow us to explore some of the best practices of using TypeScript with HarperDB.

We’ll also use a layered architecture to separate our code. This will allow us to have a better separation of concerns and make our code more maintainable. Layered architectures allow TypeScript to shine because we can use interfaces to define our contracts and make sure that our code is following the correct structure.

We will have at least three layers:

• Presentation layer: This is the layer that interfaces with the user. It can be a CLI, a web application, or even a mobile application. This layer will be responsible for receiving the user input and sending it to the next layer. In our case, we’ll have the API, which will be a REST API that will receive the user input and send it to the next layer. But this allows us to separate the real application logic from the presentation layer, which makes us able to shift the presentation layer to another technology without having to change the application logic. So we could add a CLI, a GraphQL endpoint, gRPC, or anything else without having to change the underlying structure.
• Domain or service layer: This is the layer that will have the business logic of our application. It will be responsible for receiving the validated user input and acting upon it. It will also be responsible for receiving the data from the data layer and transforming it into the correct format for the presentation layer. This layer will be the one that will have the most logic, and can be separated in multiple parts. The domain layer can be accessed by any other layers as it’s a core part of the system.
• Data layer: As the name says, this is the layer that will be responsible for the data, data can come from any source, a database, an external client, etc. It will be responsible for receiving the data from the domain layer and transforming it into the correct format for the database. It will also be responsible for receiving the data from the database and transforming it into the correct format for the domain layer. This layer will be the one that will have the least logic, but it’s the most important, because this is where we will add our database logic, and our database communication.

This is pretty close to the famous MVC Architecture, but it takes a bit of the definitions from Domain Driven Design and Clean Architecture.

The domain layer

Before creating any layers, we need to model our domain object, which is the to-do item. This will allow us to have a better understanding of what we need to do and how we need to do it. It will allow us to understand what is the shape of our object and how we will manipulate it.

Let’s start with a domain folder inside src, there we will create a file called TodoItem.ts. This will be our domain object, so let’s add the following code to it:

import { randomUUID } from 'node:crypto'

export class TodoItem {
  constructor(
    public title: string,
    public dueDate: Date,
    readonly id: string = randomUUID(),
    public completed: boolean = false,
    readonly createdAt: Date = new Date()
  ) {}
}

This is a simple class that will represent our to-do item. It has a constructor that receives the title and due date, and sets the other properties. The id is a random UUID, the completed is false by default, and the createdAt is the current date.

So we can now create a new to-do item by running new TodoItem('My first to-do item', new Date()). This will create a new to-do item with the title My first to-do item and the due date as the current date.

Tip: You can check the Node.js documentation to know more about the randomUUID function.

Let’s add some features to our domain object to make it more useful. We’ll add a toJSON method that will return the object as a JSON string, and a fromObject static method that will receive an object that matches out Data Object and return a new instance of the class.

For this we will need to create a schema that we can compare and validate our object against, this is the perfect use case for Zod! Zod is a TypeScript-first schema validation library that allows us to create schemas and validate our objects against them. Let’s install it by running npm install --save zod.

To define the schema we have two options:

1. We define it in a new file and import it in our domain object
2. We define it inside the domain object

I personally prefer the second option since both the schema and the domain object are tightly coupled and part of the same object, so it makes sense to have them in the same file. But you can choose the one that makes more sense to you.

Let’s add the following code to the top of our domain object:

import { z } from 'zod'

const todoItemSchema = z.object({
  title: z.string(),
  dueDate: z.date(),
  id: z.string().uuid(),
  completed: z.boolean().default(false),
  createdAt: z.date().default(new Date())
})

export type TodoObjectType = z.infer<typeof TodoObjectSchema>

Note: It’s also possible to somewhat mimic what we are doing in the z.infer<typeof TodoObjectSchema> by using the InstanceType utility type, but then we would need to strip out the methods from the type, so I prefer to use the infer method to also create a clear sense of separation of what is our domain object (the class) and also the data transfer object (the JSON)

We will then use this schema to make sure our object is a valid to-do item. Let’s change the fromJSON function in our domain object:

static fromObject(todoObject: TodoObjectType): InstanceType<typeof TodoItem> {
  TodoObjectSchema.parse(todoObject) // This will throw an error if the object is not valid
  return new TodoItem(todoObject.title, todoObject.dueDate, todoObject.id, todoObject.completed, todoObject.createdAt)
}

This will parse the JSON string and return a new instance of the class. We can also add a toObject to turn the class into a serializable object, and a toJSON method that will return the JSON string, this will be useful when we need to send the object to the database. Let’s add the following code to our domain object:

toObject() {
  return JSON.stringify({
    title: this.title,
    dueDate: this.dueDate,
    id: this.id,
    completed: this.completed,
    createdAt: this.createdAt
  })
}

toJSON() {
  return JSON.stringify(this.toObject())
}

Tip: One other thing that we can do here is to not use the toObject method and instead use the shorthand { ...item }, which will automatically convert it into an object. But I prefer to have a method that I can call to make it more explicit. You can also return { ...this }

Our final domain object will look like this:

import { randomUUID } from 'node:crypto'
import { z } from 'zod'

const TodoObjectSchema = z
  .object({
    title: z.string(),
    dueDate: z.date({ coerce: true }),
    id: z.string().uuid().readonly(),
    completed: z.boolean().default(false),
    createdAt: z.date({ coerce: true }).default(new Date()).readonly()
  })
  .strip()
export type TodoObjectType = z.infer<typeof TodoObjectSchema>

export class TodoItem {
  constructor(
    public title: string,
    public dueDate: Date,
    readonly id: string = randomUUID(),
    public completed: boolean = false,
    readonly createdAt: Date = new Date()
  ) {}

  toObject() {
    return JSON.stringify({
      title: this.title,
      dueDate: this.dueDate,
      id: this.id,
      completed: this.completed,
      createdAt: this.createdAt
    })
  }

  toJSON() {
    return JSON.stringify(this.toObject())
  }

  static fromObject(todoObject: TodoObjectType): InstanceType<typeof TodoItem> {
    TodoObjectSchema.parse(todoObject)
    return new TodoItem(todoObject.title, todoObject.dueDate, todoObject.id, todoObject.completed, todoObject.createdAt)
  }
}

The data layer

Now that we have our domain object, we can start creating our data layer. This layer will be responsible for communicating with the database and transforming the data from the database into the correct format for the domain layer. It will also be responsible for transforming the data from the domain layer into the correct format for the database.

Since we’re using Harper, all our communication with the DB is done through an API! Which is extremely useful because we don’t need to set up complicated drivers or anything like that. So let’s create a new file in a data folder called TodoItemClient.ts. This will be our HarperDB client.

Tip: It’s a best practice to name external APIs as ‘clients’, if we had any other data layer, let’s say a queue system that’s not connected through an API, we could just name it queueAdapter or queue and it would be fine. This is not a rule, but I personally think it’s easier to understand what the file is doing, if an external agent or an internal driver.

Our client is an HTTP API, so let’s use the native fetch from node to communicate with it (remember that the fetch api is only available in node from version 18 and up). Let’s add the following code to our TodoItemClient.ts file:

import { TodoItem, TodoObjectType } from '../domain/TodoItem.js'

export class TodoItemClient {
  #defaultHeaders: Record<string, string> = {
    'Content-Type': 'application/json'
  }
  credentialsBuffer: Buffer

  constructor(
    private readonly url: string,
    private readonly schema: string,
    private readonly table: string,
    credentials: { username: string; password: string }
  ) {
    this.credentialsBuffer = Buffer.from(`${credentials.username}:${credentials.password}`)
    this.#defaultHeaders['Authorization'] = `Basic ${this.credentialsBuffer.toString('base64url')}`
  }

  async upsert(data: TodoItem) {
    const payload = {
      operation: 'upsert',
      schema: this.schema,
      table: this.table,
      records: [data.toObject()]
    }
    const response = await fetch(this.url, {
      method: 'POST',
      headers: this.#defaultHeaders,
      body: JSON.stringify(payload)
    })
    if (!response.ok) {
      throw new Error(response.statusText)
    }
    return data
  }

  async delete(id: string) {
    const payload = {
      operation: 'delete',
      schema: this.schema,
      table: this.table,
      hash_values: [id]
    }
    const response = await fetch(this.url, {
      method: 'POST',
      headers: this.#defaultHeaders,
      body: JSON.stringify(payload)
    })
    if (!response.ok) {
      throw new Error(response.statusText)
    }
  }

  async findOne(id: string) {
    const payload = {
      operation: 'search_by_hash',
      schema: this.schema,
      table: this.table,
      hash_values: [id],
      get_attributes: ['*']
    }
    const response = await fetch(this.url, {
      method: 'POST',
      headers: this.#defaultHeaders,
      body: JSON.stringify(payload)
    })
    if (!response.ok) {
      throw new Error(response.statusText)
    }
    const data = (await response.json()) as TodoObjectType[]
    if (data[0] && Object.keys(data[0]).length > 0) {
      return TodoItem.fromObject(data[0])
    }
    return null
  }

  async listByStatus(completed = true) {
    const payload = {
      operation: 'search_by_value',
      schema: this.schema,
      table: this.table,
      search_attribute: 'completed',
      search_value: completed,
      get_attributes: ['*']
    }
    const response = await fetch(this.url, {
      method: 'POST',
      headers: this.#defaultHeaders,
      body: JSON.stringify(payload)
    })
    if (!response.ok) {
      throw new Error(response.statusText)
    }
    const data = (await response.json()) as TodoObjectType[]
    return data.map((todoObject) => TodoItem.fromObject(todoObject))
  }
}

As you can see this has all the methods we need to communicate with the database. We have the upsert method that will create or update a record, the delete method that will delete a record, the findOne method that will find a record by its hash, and the listByStatus method that will list all the records that match a certain value.

Tip: You can check the HarperDB documentation to know more about the operations.

The service layer

The service layer will be the glue between all the other layers. In an application that’s this simple, it’s usually not very useful, but it’s a good practice to have it, so we can add more logic to it later on. Let’s create a new folder called services and a new file called TodoItemService.ts. This will be our service layer.

The service layer will receive sanitized user input, perform any business logic and then send it to the data layer. It will also receive data from the data layer and transform it into the correct format for the presentation layer.

Let’s add the following code to our TodoItemService.ts file:

import { TodoItemClient } from '../data/TodoItemClient.js'
import { TodoItem, TodoObjectType } from '../domain/TodoItem.js'

export class TodoItemService {
  #client: TodoItemClient

  constructor(client: TodoItemClient) {
    this.#client = client
  }

  async findOne(id: string) {
    return this.#client.findOne(id)
  }

  async findAll() {
    return [...(await this.findPending()), ...(await this.findCompleted())]
  }

  async findCompleted() {
    return this.#client.listByStatus(true)
  }

  async findPending() {
    return this.#client.listByStatus(false)
  }

  async create(todoItem: TodoObjectType) {
    const todo = new TodoItem(todoItem.title, todoItem.dueDate)
    return this.#client.upsert(todo)
  }

  async update(todoItem: TodoObjectUpdateType) {
    const todo = await this.#client.findOne(todoItem.id ?? '')
    if (!todo) {
      throw new Error('Todo not found')
    }
    todo.completed = todoItem.completed ?? todo.completed
    todo.dueDate = todoItem.dueDate ?? todo.dueDate
    todo.title = todoItem.title ?? todo.title
    return this.#client.upsert(todo)
  }

  async delete(id: string) {
    return this.#client.delete(id)
  }
}

See that, while in the client implementation on a lower layer, we have a more generic logic which finds by status. In the service, we already separated the commands into finding pending and completed items.

Also, we implemented a findAll method which calls the listByStatus method twice and then merges the results. This is a good example of how we can use the service layer to add more logic to our application without actually adding more logic to the data layer.

Another important aspect to notice is how the service layer already assumes that all the data will be sanitized. This is a good practice because it allows us to have a better separation of concerns. The presentation layer should be the one validating the data in the route, and then sending it to the service layer. The service layer should assume that the data is already validated and sanitized.

Tip: In any case, we have already implemented another level of validations in our Domain object when we are receiving objects because TypeScript will only enforce them at the compile time, so we can be sure that the data is valid.

The last thing to notice is that, now that we have moved up a level, the service layer is taking as a parameter, the layer below, which means that we need to pass an instance of the data layer client to the service layer. This is called inversion of control and it’s a part of the Dependency Inversion Principle.

This principle states that the higher level layers should not depend on the lower level layers, but instead, they should depend on abstractions. In our case, the service layer depends on the data layer, but it doesn’t depend on the implementation of the data layer, it depends on the abstraction of the data layer, which is the client.

We will do the same with the presentation layer.

The presentation layer

Now that we have our data layer, we can start creating our presentation layer. This layer will be responsible for receiving the user input and sending it to the next layer. In our case, we’ll have the API, which will be a REST API that will receive the user input and send it to the next layer.

Let’s create a new folder called presentation and a new file called restAPI.ts. This will be our REST interface.

Usually we use a web framework to avoid having to recreate everything. In this example we’ll use a very fast framework called Hono, just to be away from Express for a while.

Install it and then it’s adapter for Node.js by running by running npm install --save hono @hono/node-server.

The implementation of the service layer usually falls into the Factory Pattern, which is a creational pattern that allows us to create objects without having to know the implementation details. In our case, we’ll use a factory to create the Rest API client so we can receive (via dependency injection) the service layer.

This translates to something like this:

import { Hono } from 'hono'
import { TodoItemService } from '../services/TodoItemService.js'

export async function restAPIFactory(service: TodoItemService) {
  const app = new Hono()
  app.get('/api/todos/:id', async (c) => {})
  app.get('/api/todos', async (c) => {})
  app.post('/api/todos', async (c) => {})
  app.put('/api/todos/:id', async (c) => {})
  app.delete('/api/todos/:id', async (c) => {})
  return app
}

This is a very simple factory that receives the service layer and returns a new instance of the Rest API client. We’ll implement the routes in a moment, but first, we’ll go back to our index.ts file in the src directory. This will be our entrypoint for the application.

There we’ll initiate the environment variables, as well as the database client and the service layer. Let’s add the following code to our index.ts file:

import { z } from 'zod'
import { TodoItemClient } from './data/TodoItemClient.js'
import { TodoItemService } from './services/TodoItemService.js'
import { restAPIFactory } from './presentation/api.js'
import { serve } from '@hono/node-server'
const conf = {
  host: process.env.HDB_HOST,
  credentials: {
    username: process.env.HDB_USERNAME,
    password: process.env.HDB_PASSWORD
  },
  schema: process.env.HDB_SCHEMA,
  table: process.env.HDB_TABLE
}

const EnvironmentSchema = z.object({
  host: z.string(),
  credentials: z.object({
    username: z.string(),
    password: z.string()
  }),
  schema: z.string(),
  table: z.string()
})

export type EnvironmentType = z.infer<typeof EnvironmentSchema>

export default async function main() {
  const parsedSchema = EnvironmentSchema.parse(conf)
  const DataLayer = new TodoItemClient(
    parsedSchema.host,
    parsedSchema.schema,
    parsedSchema.table,
    parsedSchema.credentials
  )
  const ServiceLayer = new TodoItemService(DataLayer)
  const app = await restAPIFactory(ServiceLayer)
  serve({ port: 3000, fetch: app.fetch }, console.log)
}

await main()

Note: We could have created another file called config.ts and moved both our EnvironmentSchema and conf object there, but since we are only using it in the index.ts file, I prefer to keep it there. However, if you receive that configuration somewhere else, you should create a config.ts file and move it there.

Back to our restAPI.ts file, let’s implement the routes. Most of them will only have path parameters, so I’ll just put them here and explain the logic:

import { Hono } from 'hono'
import { TodoItemService } from '../services/TodoItemService.js'

For the post and put routes, we will also need to validate the data coming in, Hono has a validator for Zod that we can use as a middleware, let’s install it with npm i @hono/zod-validator.

We can import zValidator from it and add it after our route name, but before our handler, like this:

app.post('/api/todos', zValidator('json', ourSchema) async (c) => {})

But we’ll need a few things here, first, we’ll need a new type to represent the creation type, and another one to represent the update type. Let’s add the following code to our TodoItem.ts file:

export const TodoObjectCreationSchema = TodoObjectSchema.omit({ id: true, createdAt: true, completed: true }).extend({
  dueDate: z.string().datetime()
})
export const TodoObjectUpdateSchema = TodoObjectSchema.omit({ createdAt: true }).partial().extend({
  dueDate: z.string().datetime().optional()
})

export type TodoObjectType = z.infer<typeof TodoObjectSchema>
export type TodoObjectCreationType = z.infer<typeof TodoObjectCreationSchema>
export type TodoObjectUpdateType = z.infer<typeof TodoObjectUpdateSchema>

We are creating new narrower types from a wider type generated by Zod. We need to update this type in the service file:

async create(todoItem: TodoObjectCreationType) {
  const todo = new TodoItem(todoItem.title, new Date(todoItem.dueDate))
  return this.#client.upsert(todo)
}

async update(todoItem: TodoObjectUpdateType) {
  const todo = await this.#client.findOne(todoItem.id ?? '')
  if (!todo) {
    throw new Error('Todo not found')
  }
  todo.completed = todoItem.completed ?? todo.completed
  todo.dueDate = new Date(todoItem.dueDate ?? todo.dueDate)
  todo.title = todoItem.title ?? todo.title
  return this.#client.upsert(todo)
}

Now we can use those types in the presentation layer. Let’s add the following code to our restAPI.ts file:

app.post('/api/todos', zValidator('json', TodoObjectCreationSchema), async (c) => {
  try {
    const todoItemObject = await c.req.json<TodoObjectCreationType>()
    const todo = await service.create(todoItemObject)
    c.status(201)
    c.json(todo.toObject())
  } catch (err) {
    c.status(500)
    c.json({ error: err })
  }
})

Now for the update route:

app.put('/todos/:id', zValidator('json', TodoObjectUpdateSchema), async (c) => {
  try {
    const todoItemObject = await c.req.json<TodoObjectUpdateType>()
    const todo = await service.update({ ...todoItemObject, id: c.req.param('id') })
    c.status(200)
    return c.json(todo.toObject())
  } catch (err) {
    c.status(500)
    return c.json({ error: err })
  }
})

And that’s it! We have our presentation layer ready to go!

Testing

Testing our application is a matter of running npm run start:dev and making requests to it. To test it better I’ll leave a Hurl file in the repository that you can use to test the API. You can run it using hurl --test ./collection.hurl. This will run all the tests and make sure that everything is working as expected.

You can also make requests yourself to the API using curl or any other tool you prefer. Then check your HarperDB studio to see if the data was correctly inserted.

Conclusion

In this article, we learned how to set up a TypeScript project with HarperDB, we learned how to separate our code into layers, and we learned how to test our application. We also learned some best practices along the way.

The idea is that those layers are not set in stone, you can add more layers if you need to, or remove some layers if you don’t need them. The important thing is to have a clear separation of concerns and to make sure that your code is maintainable.

Stackademic

Thank you for reading until the end. Before you go:

• Please consider clapping and following the writer! 👏
• Follow us on Twitter(X), LinkedIn, and YouTube.
• Visit Stackademic.com to find out more about how we are democratizing free programming education around the world.

Best practices for HarperDB projects using TypeScript was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

In the previous articles that I’ve written about HarperDB, we’ve explored the realms of Kubernetes, and Helm. Now it’s time to step back a little and try to understand another cool feature that it offers in this short and straight-to-the-point article.

Let’s imagine we work for a company that provides business intelligence on productive processes for big factories across the world and you’re launching a new product; Intelligent factories! To do that, the factories would be equipped with the most varied types of sensors that monitor several of the machines’ key properties, like pressure, temperature, and weight put on it.

The problem is that all this data needs to be sent back to the company’s main servers so we can apply our machine learning models and big data analysis on top of them. And they’ve asked you to provide a nice architecture to make it happen. The process has a few rules:

• The sensors send data at a very fast rate, so sending them as you receive would not be wise as it would clutter the network, making data streaming a sub optimal solution.
• The data should be stored in a database at the company in raw format.
• The sensors will keep sending data even in case of a network failure. You need to sync that data with the company’s servers as soon as the network returns.
• The company must be able to send configurations to the sensors installed in the customers from the HQ, without the need for a local visit.

How can you perform all these tasks with the minimum amount of effort and using the best technology? Enters HarperDB clusters.

Clusters

When we say clusters, the base idea that comes to us is something like Kubernetes, right? A bunch of virtual machines that behave as a single, big one. However, HarperDB takes this idea a step further. Since we’re talking about a database, the concept of “work as one” boils down to having the same data in all instances eventually, and this is, in fact, the concept of a cluster of databases.

However, in other DBs, all the data will be replicated across the whole cluster no matter what, they’ll be identical eventually, then why can’t you choose which data you want to sync?

When you cluster two or more instances of a HarperDB database together, they’ll ask you which data you wish to share, this is called a subscription. So, basically, what HarperDB has is a very robust and fancy implementation of a publish/subscribe model that works at the table level and has a fault-tolerant mechanism that allows it to lose the connection at any given time and automatically re-synchronize the data once it’s back up.

How do clusters work?

I won’t extend myself in this part as HarperDB has a very nice documentation about it, but the idea is that each database composes a node in the cluster, and the whole group of nodes in a cluster and their configurations is called a topology.

To send and receive data, the nodes rely on channels, which are named as schema: table, each channel represents a connection between two nodes, sending or receiving data from a specific table. Channels have two options, they can either be publishers, subscribers, or both.

A publishing channel will post all the changes of that specific table to any other nodes that are subscribing to it, let’s see an example. If I wanted to publish all the changes from the schema named dev on the table dog from the first node to the second one, I could create a publish channel called dev:dog.

On the other hand, I could express it differently, I could say that I want to listen to all the changes in the dog table in node 1, so I can subscribe to it:

When you create a subscription in any node, any changes to that particular table will be synced to the other tables, any new data on dev:dogwill be published to the other node, as well as any updates or removals. If the table doesn’t exist in one of the nodes, it’ll also be created, however, destructive operations like drop won’t be propagated.

Creating a cluster

So, you decide to create a proof of concept to see if your idea to use HarperDB’s clusters will work. Since HarperDB has a Docker image with clustering available, we’ll start by creating a Docker Compose file.

The idea is to simulate two instances of a HarperDB node and connect them both into a cluster. For this we’ll create two services in your Docker Compose, the first will be the one representing the sensor:

We’ll open ports 9925, 9926 and 62344, but since we’ll spin up another service in the same computer, we cannot just use the same ports, so we’ll map them to 9900, 9901, and 6200 respectively. We’ll enable clustering in the environment variables, then we’ll set the cluster port to 62344 as we set in the port manifest. Lastly, we’ll name the node as harper-edge.

For the second instance that will represent the company’s server, we’ll copy the first part and just change the names and ports, the final file will be like this:

We are just summing 1 in the ports so they don’t conflict, and also changing the name of the node. The important part here is that the cluster user and password must be the same in both services.

Let’s spin that up with docker compose up, you should see the result of two HarperDB instances being run. Now let’s go to the HarperDB Studio and register them. Just create your account, organization, and click on register a new user-managed instance. This should be the data we have:

Select the free instance and accept the terms, we should be ready to go:

Let’s do the same for the other one:

What will change will only be the port number, which is now 9902.

Connecting the nodes

We won’t create any tables on any of the instances. Instead, let’s jump into our studio and go to the “Cluster” tab on any of those instances:

As you can see, we have our other node listed, but when we try to connect we get an error:

Since we’re using Docker, the instance is not available through the HarperDB studio to be connected to the other node in the cluster, in this case, we’ll need to take the matters into our own hands, literally.

HarperDB has an API that allows you to manually create a connection between two nodes. On any request tool you have — like Postman, Insomnia, or any other — use the URL: http://localhost:9902 in a POST request. You can use any of the hosts to do what we’re about to do, but to keep the idea of the project, let’s connect to the host one representing the company’s database.

In the auth section, we’ll use a basic HTTP auth, the username and password are the ones we defined in the compose file, in this case both of them are admin. Now we’ll create a JSON body that looks like this:

So, from the company’s database, we want to publish configurations and subscribe to sensor data, let’s tell the node that with two objects inside the subscriptions key:

Now, we go back to our studio and log on to the harper-host instance. We’ll create our schema called default and a table called configs.

Now, let’s add a simple data to that table by clicking the + button on the top right:

After saving, let’s switch to the harper-edge instance, and look! We now have a configs table and inside that table we have the same item we just added:

Let’s do the same on the harper-edge instance, and add a table called sensor_data with a hash of id, then add some data on it:

And if we switch back to the host, we’ll also have the same data over there:

This is valid even if we delete the data on one of the sides, in this case the data on the other end will also be deleted.

Conclusion

This was the first glimpse of this amazing feature. Stay tuned for the next tutorials on how we can use Harper’s pub/sub to make it work in our favor in other real-world examples.

If you find this helpful, please click the clap 👏 button below a few times to show your support for the author 👇

🚀Join FAUN & get similar stories in your inbox each week

Simple Multi-Node Data Replication with HarperDB Pub/Sub was originally published in FAUN.dev() 🐾 on Medium, where people are continuing the conversation by highlighting and responding to this story.

A while ago, I wrote this article, which explained how we could run a HarperDB instance using a Kubernetes cluster hosted on Azure!

As you can see, this article is pretty long, it has a series of commands and a series of manifest files that we create and need to keep updated in order to make the database work properly in the cluster.

What if I told you we could do this using a single command?

Helm

Kubernetes alone is a great tool; however, no one is the greatest alone, and this is why Kubernetes has a younger brother called Helm.

Helm is one of those tools created with the purpose of filling a small gap in an existent technology, sometimes this gap is so huge that it becomes a very respectable and useful tool, so much that is even quite difficult to use the original tool without it.

I explained a lot about Helm in this article on FreeCodeCamp some time ago, so I won't be explaining it all over again. Instead, I'll quickly skim through what you need to know the most about it.

The purpose that Helm serves is basically to pack manifest collections into Charts. Charts are like application libraries — yes, just like NPM, NuGet, pip, gems and so on — the only difference is that it doesn't contain actual code, but a series of go-like templates that will eventually be parsed into useful YAML files, which are the Kubernetes manifests.

This way we can group all the manifests from a single application into one Chart and install it in a single command. But, beyond that, what is even more useful than being able to install entire apps in a whim is the possibility to compile templates just-in-time, which means we can have variable data inside those templates.

For example, in the other article, we had this code:

This is a Kubernetes deployment for HarperDB, but it contains some environment variables and this data is often changed, so we could do this instead:

See the {{ .Values.HDB_USERNAME }} , well, that's a template variable. And we can change it in runtime.

Preparing the ground

Below I’ll be using Azure, but you can use whatever cloud provider you want. Which means that, if you’re not using Azure, then you probably don’t need the Azure CLI.

Before we start, head over to the Helm website and install the Helm binary, as well as the Azure CLI and the Kubectl binaries.

If everything went correctly, you should have three new commands in your terminal: kubectl , az , and helm .

First, use az login to log in to your Azure account. Then, you should create a resource group with the command az group create -n harperdb-helm after that let's create our cluster with the following command:

The whole process takes about a minute or two, so be patient. After it's done, you can run az aks get-credentials -n harperdb-helm -g harperdb-helm --admin and this should populate your kubeconfig file with the credentials to the cluster.

If everything is fine, then when you issue kubectl get nodes you should see a list with one node.

Helm charts

As I mentioned in the beginning, Helm groups the packages into charts. Charts have a very specific directory structure.

To create a chart we simply type helm create harperdb and this will give us another directory with the following structure:

└── harperdb
├── Chart.yaml
├── charts
├── templates
│ ├── NOTES.txt
│ ├── _helpers.tpl
│ ├── deployment.yaml
│ ├── hpa.yaml
│ ├── ingress.yaml
│ ├── service.yaml
│ ├── serviceaccount.yaml
│ └── tests
│ └── test-connection.yaml
└── values.yaml

You can find a detailed explanation on the directory structure on my article, but what we need to know is that we can delete all the files inside the templates directory, we can also delete the charts directory. The final directory structure will be:

└── harperdb
├── Chart.yaml
├── templates
└── values.yaml

The Chart.yaml file is the one that names our package, you can open and edit it to be like this:

Template files

Then we can start by creating our template files. It's as simple as copying and pasting our previous templates from this article into their own files. Let's start by the deployment. Create a new deployment.yaml file inside templates with this content:

Now we'll apply the template variables into this document, this will be the final result:

Notice that we're using some functions like default , required , quote and the special namespace .Values . Golang templates (the type that helm uses) have several functions to help formatting data when used.

The default and required functions, as you may expect, define values that are default, in this case, we're getting the namespace of the release unless we say explicitly that we want it to be somewhere else. Same goes for required , it'll pop an error if it fails to receive the data.

The .Values namespace refers to our values.yaml file, it's where we'll define the values for those variables.

Next, create a new file called persistentVolumeClaim.yaml with this content:

And we'll do the same thing, replace the variable values for placeholders:

Now we'll jump to the service, create a service.yaml file with these contents:

And this will be the version with the placeholders:

Values

This would be all files that we need for the templating part. Now let's create our values file. As you can see, the values.yaml file already has some content, you can delete it all and we'll create all the variables that we're using in the templates. The final file will look like this:

The values we put in the file will be the default values of the placeholders they match, for example, the .Values.name will match the name: harperdb value of the YAML, which means this has a default value.

Also pay attention that we can scope variables inside other objects, like we're doing for service.port and env. Also, about the env those are environment variables, which don't contain a default value.

Install the chart

To deploy our application, we need to install the chart to the cluster. But before, let's check if everything is correct. To do that we'll render the template in our terminal using the following command:

The -n flag tells us the namespace we want to install, while the --set flags will update the values inside the values.yaml file, and consequently, our manifest files as well.

If all went well you should have this output:

Now that everything is fine, we can install our chart with the following command:

We're creating a release named harperdb out of a local chart (the last argument), you can name your release whatever you want and also host your chart (but this will be a matter for other tutorials).

You can check the deployment using the command helm list -n database. To remove the release just type helm delete harperdb -n database.

To connect to the database, you may refer to the previous article and jump to the "Accessing HarperDB" session.

If this post was helpful, please click the clap 👏 button below a few times to show your support for the author 👇

🚀Developers: Learn and grow by keeping up with what matters, JOIN FAUN.

Running HarperDB in Kubernetes in one command was originally published in FAUN.dev() 🐾 on Medium, where people are continuing the conversation by highlighting and responding to this story.

When working with any sort of application, one of the biggest challenges is to make it reusable and maintainable. This is why we usually choose containers as the tool to get around this problem.

Containers are simple to build and easy to maintain. A while ago I wrote this article on FreeCodeCamp that explains a lot about what containers are and why we should use them.

Now, while building an application recently, I ran into another problem: How can I run my database, using HarperDB, in a container? And then how can I install it using Kubernetes?

After some brainstorming I came up with a solution, and now it’s the time to share that with you!

But, first things first, what is HarperDB?

HarperDB

HarperDB is a multi-paradigm, general-purpose database that is designed to be fast and easy to use. It encapsulates SQL and NoSQL functionality, CSV data aggregation and a whole lot of helpers like Math.js for working with math, GeoJSON support for working with geographical data, and moment for working with dates.

Ok, but what’s the big catch? Other databases already do this. The catch is that HarperDB stores this as a unified data structure and serves it through a unique storage algorithm that makes it really fast for all the different types of data.

On top of that, HarperDB is also projected to be a full-fledged solution to build not only your database alone, but also a complete API that interacts with that through the use of Custom Functions (which I’ll talk about in another article), websockets, and the cherry on top is that it doesn’t require a specific driver to work with. It exposes a standard REST API that can be used by any language, so you can both query data and perform operations using simple HTTP calls.

Here’s a quick diagram of how HarperDB works, taken straight from the HarperDB website:

In short, I wanted to try it out and wasn’t disappointed! Now, how can we install this database in a Kubernetes environment?

Kubernetes and Databases

Usually, when dealing with databases, we tend to install it on a separate computer or VM, and connect our application to that. While this is a good option to make it easier to manage, it’s not the best option to make it faster, nor distributable, highly available, or reliable.

To do that, we need to distribute the database into several machines using a cluster approach, which means we have a main control plane, which is the main connection point for a database, and several other instances of the same database on which the control plane will distribute the load. These instances are called nodes.

Some nodes can be read only, some can be write only, some can be both. This allows us to make sure we have the correct permissions for each node, and we can also make sure that we don’t have any data loss or corruption. When any data is inserted, deleted, or changed in the database, these nodes publish a message to other nodes to make that change too, so that the data is always consistent. However, it takes a while for this data to be replicated when we have a large infrastructure, this is what we call eventual consistency.

In this article I’ll be creating a single HarperDB instance on Kubernetes, however, I plan to show you how to create a cluster of HarperDB instances in future articles.

Containerizing HarperDB

Most databases already have a container-ready approach, and Harper is not different. You can find the containerized version of HarperDB in their Docker Hub page, it’s very straight-forward to install and run. Before putting the database in Kubernetes, let’s make sure we can run it locally using Docker.

If you don’t have Docker installed, you can install it from the Docker website.

The simple and easy command to run is:

HarperDB needs port 9925 to be opened so we can connect it to the HarperDB Studio application, so we can manage it straight from the browser.

Aside from that, we need to remember that containers are ephemeral, which means they do not persist after they are stopped. This is why we need a volume to persist the data, for that we can add the -v flag in our Docker command, pointing to the /opt/harperdb/hdb directory inside the container:

In this command we’re telling Docker to mount the /opt/harperdb/hdb directory in a local folder called /.hdb, so that we can persist the data. After the command is run, we can ls -la the /.hdb directory to see that it’s actually mounted:

Now, we go to the HarperDB Studio application and login. If you don’t have an account yet, go to the sign-up page and create one, it’s free. Then create an organization for you and you should land on this page:

Let’s create a local instance by clicking the Register User-installed Instance button:

Let’s fill up the details of the instance, and then click the instance details button:

Then we select the free tier and click next:

Confirm the terms of service and Add Instance. You should end up with a local registered instance of the database:

If you click it, you should have access to all your schemas and tables. So that’s what we need to do.

Migrating to Kubernetes

First, let’s set up a plan of what we need to do:

1. Create a Kubernetes cluster
2. Create a namespace called database so we can organize our resources
3. Create a deployment for HarperDB so we can deploy it to the cluster
4. Create a persistent volume claim for the /opt/harperdb/hdb directory
5. Create a service for HarperDB so we can port-forward it locally and connect to it from the browser

Since we’ll not be exposing the database to the internet, we won’t create an Ingress rule for it, instead, we’ll only connect to it from inside the cluster.

Create a Kubernetes cluster

There are a ton of ways to create a new Kubernetes cluster, but the easiest and fastest way is to use a managed cluster. In this tutorial we’ll be using Azure’s AKS, but you can use any other provider.

The first thing is to log in to your Azure account on the Azure Portal, if you don’t have an Azure account, just create one in the Azure website. There are two ways to create a managed AKS cluster, one of them is through the Azure CLI, the other is through the portal itself, which is the way we’ll be doing this tutorial.

Search for “Kubernetes” in the Azure Portal, and click on the Kubernetes Services result:

Then click on create dropdown and create a new cluster:

Let’s create a new resource group called harperdb-aks, let’s change the preset to development to save some money since we’ll not be using the cluster for production, then name the cluster harperdb, choose your preferred region:

Let’s select the B2s instance in the instance picker and remove the autoscale method, since we’ll be using a fixed size cluster of 1 single node:

Click the blue Review+Create button to create the cluster:

The process will take a while to complete, so let’s wait until it’s done.

While you wait, take your time to install and login to the Azure CLI if you haven’t done so yet, because we’ll need it to connect to the cluster.

After the process is complete, jump to your terminal, start your az cli and install the kubectl tool with az aks install-cli. After that we’ll download the credentials to our kubeconfig file, so we can connect to the cluster using az aks get-credentials -n harperdb -g harperdb-aks — admin.

If everything went well, you should be able to connect to the cluster with kubectl get nodes and get a response with a single node like this:

Let’s create our namespace with kubectl create namespace database, and now we’re able to create our manifests.

Create manifests

To start the manifest creation, we’ll need to create a deployment for HarperDB, so we can deploy it to the cluster. Let’s create a new file called manifests.yaml where we’ll add all the manifests we’ll need. In this file, we’ll start with the deployment:

Before we go further, some explanation on volumes is necessary. Since we’re dealing with managed volumes on Azure, we don’t need (and can’t) create a volume inside the host nor inside the pod because they’ll be deleted when we delete the resources. What we want to do is to delegate the creation process to Azure through StorageClasses and PersistentVolumeClaims.

The usual process is to create a PersistentVolume and then claim it with a PersistentVolumeClaim

The idea is that we declare that we want to claim a determined amount of space from the Azure pool for the volume, and then we’ll mount it to the path we want. Azure will receive this request through a Kubernetes operator that manages the CSI (Container Storage Interface) plugin and create the volume in our Azure account.

By default, Azure has two types of storage: Azure File and Azure Disk. We’ll be using the Azure File storage because it’s easier to see the files in the Azure Portal, also, clusterization is only supported in Azure File storage.

Also note that we’re mounting the volume not on /opt/harperdb/hdb but on /opt/harperdb. This is because if we mount the volume in the innermost directory, we’ll have permission problems since the outermost directory is owned by the user that runs the container, and the innermost directory is created by Azure.

The other important information is that HDB takes a small while to start, so we’re setting a livenessProbe and readinessProbe to check if the pod is ready, these probes will check the connection on TCP port 9925, when this port is open, the service is online.

Next, we’ll add the persistent volume claim:

And to finish the manifest file, we’ll add a service:

The final file will look like this:

The last thing is to apply the manifests to the cluster using kubectl apply -f ./manifests.yml. You’ll receive a message like this:

persistentvolumeclaim/harperdb-data created
deployment.apps/harperdb created
service/harperdb created

We can check if everything is fine by running kubectl get deploy harperdb -n database:

Then we can take a look on our Azure Portal and see if the volume is there. First, select Resource Groups in the portal, you can do this by searching for it or clicking on the home page.

Find a resource group that matches MC_harperdb-aks_harperdb_<location>, click it, you should see a bunch of resources.

One of these resources is our Storage Account, click it. Then, in the left panel, go to File Shares, you should see an Azure File volume starting with pvc-, click it.

Here’s our mounted volume with all HDB’s files. Now let’s access our HDB instance and check if everything is working.

Accessing HarperDB

To access the database from the outside world, since we didn’t expose it as a good practice, let’s port forward our own connection to our service connection using the following command:

You should see the following messages:

Forwarding from 127.0.0.1:9925 -> 9925
Forwarding from [::1]:9925 -> 9925
Handling connection for 9925
Handling connection for 9925
Handling connection for 9925
…

Then, let’s go to our studio in the browser and create a new instance with the credentials that we included in our deployment manifest, the username and the password are harperdb.

After that, you can follow the same steps to create a new database, create a new user, and then grant permissions to the user.

Conclusion

We made it to the end of this tutorial and I hope you enjoyed it! Now you’re able to create your own HDB instance in a Kubernetes cluster.

If you find this helpful, please click the clap 👏 button below a few times to show your support for the author 👇

🚀Join FAUN & get similar stories in your inbox each week

Using HarperDB with Kubernetes was originally published in FAUN.dev() 🐾 on Medium, where people are continuing the conversation by highlighting and responding to this story.

Recentemente estive passando pelos tópicos no DEV Community e encontrei um excelente artigo sobre algumas dicas para pessoas que queiram começar a escrever artigos técnicos. Então resolvi escrever um artigo com a minha própria opinião sobre o assunto e também referenciar algumas partes deste conteúdo sensacional.

Algumas das dicas e referências a seguir serão copiadas deste artigo somente para fins práticos, para evitar que o leitor tenha que buscar o conteúdo no artigo original. Porém, as opiniões sobre ele são próprias.

Por que escrever?

Todas as pessoas, sendo programadoras ou não, deveriam escrever sobre o que fazem e sobre o que estão aprendendo, ou então escrever somente sobre a vida que estão levando.

Um ponto interessante que é colocado no artigo é algo que não pensamos muito. Sempre que lemos um conteúdo técnico na Internet, associamos o criador daquele conteúdo como sendo uma autoridade ou pelo menos tendo certa autoridade no assunto, e isso é algo extremamente positivo para a sua carreira e também para você como pessoa.

Ser associado com experts no assunto é sempre uma boa prática. Quando as pessoas leem seu artigo na Internet, elas te reconhecem como um profissional e confiam mais no que você diz.

- Extraído da referência

E este é, entre outros, um dos pontos por que você, como pessoa desenvolvedora, deveria começar a escrever conteúdo técnico, a consolidação do seu status como profissional do desenvolvimento pode te ajudar em sua carreira futura e também influencia na maneira como você lida com as situações. Alguém que está sempre escrevendo ganha habilidades importantes para o mercado de trabalho:

• Aumenta a sua desenvoltura falada e escrita: portanto, melhora a sua forma de lidar com clientes e outros colegas, além disso, te ajuda a criar e expor argumentos de forma mais clara e concisa.
• Faz com que você tenha uma nova forma de pensar: O processo de criação de artigos é algo bastante elaborado, conforme vamos falar mais para frente, ele exige que você tenha uma organização e uma forma de construção concreta, você não vai conseguir escrever algo se simplesmente jogar suas ideias ao ar. Pensar na forma de escrita é uma ótima maneira de começar a ver o mundo de forma diferente
• Te prepara para feedbacks: Ao nos expormos na Internet estamos sujeitos todo tipo de resposta, boa ou ruim, e é importante sabermos lidar com ambas. Isso faz com que desenvolvamos a habilidade de saber responder críticas de forma ponderada e lidar com elogios de forma humilde.

Já falamos muito do que escrever desenvolve como habilidade, mas, além disso, por que devemos começar a escrever?

Consolida seu aprendizado

Você provavelmente já ouviu a frase: “Só aprende de verdade quem ensina a outra pessoa”, ou alguma de suas variações, certo?

Isto é real. Ensinar outra pessoa força você a buscar correlações e consolidar o seu conhecimento. Uma forma bastante simples de fazer isso é escrevendo sobre ele.

Escrever faz com que você precise pensar na forma mais simples e fácil de fazer a pessoa que está lendo entender o conteúdo que você quer passar, isso ajuda a consolidar sua experiência e seu conhecimento de forma simples e rápida.

Ou então, se você é como eu, sua motivação para escrever artigos pode vir simplesmente da vontade de compartilhar conhecimento com outras pessoas e querer observar e analisar pontos de vista e opiniões diferentes das suas.

Te mostra ao mundo

Como profissional, é importante que outras pessoas saibam o que você está fazendo e como você se destaca nisso, você quer que as pessoas te conheçam pelo que? Se você tem um sonho de começar a trabalhar em uma empresa mas não sabe como alcançar este sonho, uma das opções é justamente aparecer mais, afinal, todas as empresas são compostas de pessoas e estas precisam saber que você existe.

Além de uma vantagem profissional, escrever também te coloca, invariavelmente, em um patamar de pessoas que, aos olhos de outras, se tornam referências sobre o que estão falando, pois muitos vão buscar seu conteúdo para completar trabalhos de escola ou até mesmo criar projetos pessoais.

Eu, até hoje, me lembro que, em 2010, quando estava começando a aprender a programar e, mais do que frequentemente, caia no site do grande José Carlos Macoratti — na época, eu programava em .NET — e, até hoje, ele é uma das minhas maiores referências, mesmo não tendo tocado em um código C# há quase dez anos. Lembre-se da icônica frase de Isaac Newton:

Se enxerguei mais longe foi porque me apoiei sobre os ombros de gigantes

- Isaac Newton

Você pode ser um dos gigantes onde outros gigantes se apoiaram para desenvolver suas criações, você provavelmente nunca vai saber disso, mas outras pessoas — talvez aquela pessoa gerente de RH na empresa onde você tanto quer trabalhar — vão!

Captura seus pensamentos

Por último, mas não menos importante, escrever cria um repositório de conhecimento que pode ser a diferença entre o sucesso ou o fracasso de um projeto. Você não precisa escrever com o objetivo de se tornar famoso, mas sim para registrar o seu conhecimento para si, criando um arquivo de informações úteis que você pode buscar quando precisar.

Um exemplo pessoal — que já me salvou mais de uma vez — é o meu repositório de notas, um local simples que, há mais de três anos, escrevo todos os meus aprendizados de praticamente todos os cursos que já fiz em minha vida. Lá estão repositórios de exemplo, dicas e truques, ideias e até planejamentos inteiros de palestras.

Escrever sobre algo publicamente — ou mesmo de forma privada — te faz registrar e ter uma documentação mental por escrito daquele momento, pense como um snapshot do seu cérebro em uma determinada época.

Por que devs não escrevem?

Nós somos devs, não somos jornalistas ou repórteres, muito menos escritores profissionais. Tudo conspira para que o dev jamais escreva algo. Dentre os maiores problemas para devs na escrita temos:

• Timidez: Devs são pessoas naturalmente introvertidas — muitas vezes é a razão pela qual escolhemos a profissão, máquinas são muito mais simples de lidar do que pessoas — e isso impacta duramente na expressão para um mundo todo através da Internet, mas isso pode ser superado, um exemplo muito legal é o artigo da Mariane Santana, que nunca tinha escrito antes e agora está na lista dos 7 artigos mais lidos do DEV Community 🤘
• Planejamento: Devs geralmente tem ansiedade elevada, mas não adianta querermos escrever tudo de uma vez, precisamos ter um planejamento
• Falta de prática: Infelizmente aqui não podemos mudar muita coisa a não ser dizer a prática leva a perfeição… Você só vai conseguir escrever melhor se praticar escrevendo cada vez mais. A leitura também ajuda muito a aumentar o seu vocabulário de escrita e melhorar a forma como você escreve
• Medo de ser criticado: Como já mencionei, quando nos expomos na Internet, estamos sujeitos a todo o tipo de crítica, então muitas pessoas não escrevem pelo receio de serem duramente criticadas. Neste caso, não temos muito o que fazer, apenas tenha pleno conhecimento do que você está escrevendo e se sinta pronto(a) para responder perguntas — não interagir também é uma opção.

Como escrever um artigo

Defina um assunto

Você pode escrever literalmente sobre qualquer coisa. Que tal sobre a sua experiência usando uma ferramenta? Ou então o seu processo de aprendizado? Talvez sobre como seu estudo de música influenciou a sua vida como dev. Enfim, você escolhe!

Ninguém vai esperar que você escreva sobre algo que está fora da sua área de atuação, e muito menos que você seja a referência máxima em algo que você está aprendendo (desde que você deixe claro que esteja aprendendo), você pode ficar desconfortável com isso, mas por outro lado, ter uma perspectiva sobre como VOCÊ faz as coisas e como é a SUA rotina pode ajudar outras pessoas a entender como serem melhores. Pontos de vista… sempre…

Outras ideias de escrita:

• Experiências próprias sobre algum assunto
• Novidades sobre suas tecnologias favoritas
• Histórias de vida, suas ou de outros
• Aprendizados, fracassos, sucessos e lições que você teve em sua jornada

Pesquise e planeje

Um passo muito importante da escrita técnica é a busca. Você provavelmente não vai ser o primeiro a escrever sobre alguma coisa. Mas pesquise muito bem antes de começar a escrita do seu tema. Tenha também um planejamento sobre o que você vai escrever:

• Agende os seus artigos: Conforme eu falei em minha série sobre organização pessoal, tudo precisa se tornar uma tarefa planejada, e com artigos não seria diferente, planeje as datas com antecedência
• Saiba seu tema: Saiba com antecedência sobre o quê você quer escrever
• Planeje seu conteúdo: Escreva em uma em qualquer lugar, um outline do seu artigo, com os principais títulos e tópicos

Veja se existem outros artigos com o mesmo tema. Não há problema em escrever artigos sobre a mesma coisa — da mesma forma como estou fazendo aqui — apenas se certifique que não é um plágio e deixe sempre referências para o conteúdo original. Veja algumas opções:

• Conteúdo da sua experiência pessoal sobre o tema
• Uma opinião diferente
• Um adendo ao tema (como este artigo)
• Tradução para outra língua

Procure o máximo possível de pontos de vista distintos sobre o mesmo assunto, quanto mais opiniões você incorporar, mais rico seu artigo ficará.

Dando um título

O título do seu artigo é o que fará com que as pessoas se interessem em lê-lo. Então ele precisa ser bem pensado. O título deve ser claro, conciso e deve indicar o propósito do artigo. Vou usar alguns exemplos do artigo de referência traduzidos:

1. Roundup #58: Orleans 3.0, Snitch, Qual é o seu problema? Próximos 5 anos de ASP.NET Core
2. A Linguagem de Programação para Todas Comandar
3. Sofrendo de Débito Técnico?

Veja por que estes exemplos são ruins:

1. Muitas keywords, muita coisa acontecendo, o título é muito longo e parece que fala sobre absolutamente tudo
2. Muito “esotérico”, claramente parece um clickbait, mas não dá muito a entender sobre o que o material fala (isto também vale para o 3)
3. Uma pergunta ao leitor como um título não é um bom título. Ela gera dúvida e isso gera expectativa de resposta, se a resposta que você der não satisfazer o leitor, então você acabou de manchar a sua reputação para aquela pessoa específica.

Agora alguns bons exemplos:

1. Carreira em Programação e Música: O que aprendi com isso tudo?
2. Desenvolvendo uma Aplicação CRUD Node.js com PostgreSQL
3. Tutorial: Data pipeline usado MongoDB e Kafka Connect no Kubernetes

Veja que o artigo da Ana sobre música contém uma pergunta, mas ela não é direcionada ao leitor, e sim uma pergunta retórica que remete a ela mesma, explicando do que o artigo se trata.

Estrutura

Todo o artigo segue uma linha de raciocínio, isso é algo que aprendemos na escola em nossas primeiras redações, todo o texto possui:

• Título
• Introdução
• Desenvolvimento (Aqui é onde colocamos o código, imagens, exemplos)
• Conclusão
• Referências

Com artigos técnicos não é diferente, a única coisa que será um pouco diferente é a parte das Referências que é geralmente utilizada como uma seção onde você pode ligar um artigo ao resto do seu trabalho.

Tempo

Um artigo da Data Lab mostrou que o tempo ideal de um artigo é de sete a dez minutos. Isso não é uma regra, mas ajuda a te guiar para o tempo que seu conteúdo deve ter. Eu, particularmente, uso uma extensão para o VSCode que me mostra estas informações.

Porém não há problema em passar deste tempo se você está escrevendo um artigo mais detalhado ou um tutorial, afinal, é o seu conteúdo. Apenas leve em consideração a capacidade de quebrá-lo em mais de um, formando uma série, como faço com muitos artigos meus

Conteúdo

As pessoas esperam ler o conteúdo que você está dizendo que vai passar. Evite usar palavras muito complexas, ou escrever como se fosse um artigo científico — a não ser, claro, que este seja seu intuito.

Inclua imagens sempre que possível, gists e use o Carbon ou o CodePen para incluir códigos.

Algumas outras dicas de conteúdo:

• Evite ser completamente informal, mas evite também ser muito formal
• Veja aplicativos como o Grammarly (se estiver escrevendo em inglês), confie em extensões de analise de texto
• Sempre revise seu texto antes de publicar
• Veja se outra pessoa pode ler o texto para que ele possa ser revisado
• Expanda acrônimos quando forem usados pela primeira vez no artigo, por exemplo: “O uso do AKS (Azure Kubernetes Service) …”
• Prefira utilizar a primeira pessoa do plural quando escrever artigos — a não ser que seja um artigo de opinião — pois “nós” cria um senso de coletividade com a pessoa que lê
• Não faça parágrafos muito longos
• Sempre que prover dados (números, etc), cite a data e fonte de onde eles vieram

Palavras-chave

Keywords, ou palavras-chave, são importantes porque será através delas que mecanismos de busca vão indexar seu texto. Para procurar por quais tags você pode utilizar, veja alguns exemplos diretos do artigo que referenciei:

• moz.com
• app.neilpatel.com
• trends.google.com
• keywordtool.io
• wordtracker.com/scout

Use pelo menos 5 tags para indicar o que você está escrevendo, em nível decrescente de mais genérico para mais específico, por exemplo: open-source, back-end, javascript, node.js, cli

Divulgação

Não tenha medo de divulgar o seu trabalho da maior forma possível, utilize ferramentas como o MLabs, Hootsuite e outras para fazer a gestão de suas redes sociais mais utilizadas, agende seus posts. Faça uso de grupos em redes sociais que sejam especializados no que você está escrevendo, seu público está por lá.

Dica: Mantenha postagens recorrentes sobre seu artigo, mas evite duplicar o texto, muitos algoritmos de redes sociais identificam posts duplicados na mesma conta como spam.

Conclusão

Tentei escrever de forma mais simples e concisa tudo o que aprendi escrevendo artigos técnicos nestes últimos anos. Espero que, com estas dicas, você também se inspire a escrever mais e compartilhar o seu conteúdo.

Não deixe de acompanhar mais do meu conteúdo no meu blog e se inscreva na newsletter para receber notícias semanais!

Se você quer começar a escrever mas não sabe se seu artigo está legal e quer uma segunda olhada ou então você já escreve e quer compartilhar, me manda seu conteúdo através das minhas redes sociais, eu adoraria dar uma olhada!

Você pode encontrar todas elas no meu site:

Lucas Santos

Até mais!

Do zero à automação de containers em 7 minutos

Em um artigo anterior, comentei como poderíamos criar um backend GraphQL completo apenas usando uma imagem Docker e um arquivo de configuração. Tudo isso hospedado no Azure. Agora vamos aprender a automatizar os deploys que são feitos para a nossa hospedagem e a atualização automática do nosso backend!

Este projeto todo visa criar um backend para meu futuro arquivo de conteúdo que estará presente no meu site. Mas sempre que eu atualizar o backend ou mudar o schema do GraphQL vou ter que fazer todo o deploy do serviço novamente.

Então, ao invés disso, eu gostaria que, a cada push no meu branch master, eu gerasse uma nova versão do arquivo e enviasse a atualização para o Azure. Porém eu não quero ter que usar outras ferramentas para isso, quero manter toda a stack o mais simples possível, como estamos utilizando somente o GitHub e o Azure, nada mais justo do que continuar no GitHub para fazer a automação, não é mesmo?

Por isso que vamos usar os GitHub Actions

Similar a outros provedores de CI como o Travis ou o Circle, o GitHub também possui um sistema de integração e automação do repositório. A facilidade deste sistema em relação aos outros é que você já está dentro do mesmo repositório e ja está dentro da mesma ferramenta.

O projeto que vamos utilizar para automatizar será o meu repositório publico de backend:

Veja que o repositório é super simples, não contém muitos arquivos, apenas um docker-compose.yml para testes locais e o nosso arquivo yml do mongoke que será o schema GraphQL.

No topo da página, ao lado de settings, temos o botão Actions, será lá que vamos configurar a nossa automação!

O GitHub já possui uma série de workflows prontos, porém, infelizmente, ainda não temos nenhum para o que queremos fazer. Mas o que queremos fazer? Para deixar tudo mais claro, vamos listar todas as etapas do processo:

1. Recebemos um push na branch master
2. Conectamos com a Azure através de um service principal e de uma action chamada Azure/login
3. Depois vamos utilizar a action Azure/cli para poder executar o comando de deploy do nosso container

Alguns detalhes que temos que perceber:

• O cache do GitHub Pages é um pouco longo, então vamos ter que gerar um número aleatório ou uma fingerprint para colocar na URL do nosso arquivo YAML do Mongoke
• Temos uma URI do MongoDB que deve ser um segredo

Criando um secret

Primeiramente vamos tratar das nossas dependências, a dependência mais fácil de ser resolvida é criar a URL do MongoDB como um secret. Para isso vamos até a nossa aba Settings e clicamos em Secrets. Basta adicionar um novo secret clicando no link Add new Secret e preencher um nome e o conteúdo do mesmo. No caso estamos adicionando a URI do MongoDB, então vamos chamar este secret de MONGODB_URI

Permitindo ações na Azure

Para que possamos permitir que o GitHub execute ações em nosso nome na Azure, vamos precisar criar um Service Principal. Este recurso nos dá uma conta de aplicação para que possamos permitir que outras pessoas ou serviços conectem-se em nosso portal e realize ações em nosso nome.

Para criarmos este recurso, vamos usar o Azure CLI. Depois de realizar o login com o comando az login, basta executar o seguinte comando:

Para obter o ID da sua subscription basta executar o comando az account list e buscar a chave id da subscription que estiver com a chave isDefault marcada como true. Você também pode dar qualquer nome ao seu Service Principal, faça com que ele seja descritivo para saber a quem você está garantindo permissões.

Por último, outro detalhes importante é somente dar as permissões aos recursos necessários, ou seja, não vamos criar um SP para a conta TODA, mas sim somente para o Resource Group que precisamos, no meu caso, este RG se chama personal-website e é onde eu estou agrupando todos os recursos relativos ao meu site.

Este comando deve dar uma resposta em JSON do tipo:

Copie toda essa resposta e crie um novo secret no GitHub chamado AZURE_CREDENTIALS:

Agora devemos ter dois secrets criados:

Criando um workflow

Para criarmos o nosso primeiro workflow, basta voltarmos para o painel Actions ao lado de Settings e clicar no botão Set up this workflow:

Esta ação deve levar para uma nova tela com um modelo inicial do código:

Perceba que as GitHub Actions nada mais são do que um arquivo YAML que ficam em uma pasta <seu repo>/.github/workflows e este será o nome do workflow, portanto é importante que ele seja bastante descritivo. Vamos dar o nome do nosso de publish-prod.yml:

O conteúdo que temos é o seguinte:

Primeiro, vamos setar um nome para nosso workflow, este será o nome que aparecerá na UI do GitHub, então podemos deixar um pouco mais bonito:

Agora vamos definir em qual tipo de ação queremos que ele rode. Como queremos que ele rode em qualquer push ou PR no branch master, não vamos fazer nenhuma alteração, mas se precisássemos alterar esta ação, teríamos que mudar a chave on. Para verificar quais são as ações disponíveis, basta clicar no editor e apertar ENTER que um intellisense será mostrado:

Veja que temos várias ações possíveis, para detalhar melhor, veja a documentação oficial

Então vamos criar uma seção para compartilhar variáveis de ambiente e conteúdos que vamos usar na parte mais a frente do nosso script, por exemplo, o nome do container e também o nome do resource group. Para isso criamos um bloco env:

Agora vamos, de fato, criar a máquina e o que chamamos de runner, que é quem vai rodar o nosso código de testes e de publicação. Todo o workflow é composto de um ou mais jobs que podem ser executados sequencialmente ou em paralelo. No nosso caso não temos que fazer muita coisa, apenas conectar e fazer o deploy. Portando vamos modificar a seção jobs:

Iremos rodar nosso job em uma imagem do Ubuntu, veja as demais opções na documentação. Depois disso vamos configurar os nossos steps, um step é uma sequencia de tarefas que serão executadas como partes de um job, ou seja, aqui será o lugar onde vamos executar o nosso login e o nosso deploy!

Para isso vamos modificar a chave steps e vamos remover todo o conteúdo, então vamos utilizar os steps pré prontos da Azure para poder fazer o login! Podemos pesquisar na caixa de texto lateral por Azure/login:

Ao clicar no nome do step, vamos ter um tutorial de como usá-lo, neste caso é bastante simples, basta copiarmos o seguinte código para dentro do nosso step:

E será aqui que vamos setar o nosso primeiro secret, precisamos do AZURE_CREDENTIALS que criamos anteriormente para poder prover as credenciais de acesso para o login. Para usar um secret basta colocá-lo entre chaves duplas como em: ${{ secrets.AZURE_CREDENTIALS }}.

Nosso arquivo está assim:

Vamos criar um segundo step que vamos chamar de Deploy ACI, que será aonde vamos executar o nosso comando do Azure CLI. Para isso vamos utilizar outro step com o comando run que vai conter a linha que vamos executar em nosso CLI. Em nosso a caso, já com as variáveis substituídas, será esta:

Vamos observar bem a última parte onde criamos a variável MONGOKE_CONFIG_URL, esta variável sozinha não vai ser suficiente, temos que concatená-la com o valor do SHA do commit para não sofrermos com o cache. Para concatenarmos variáveis, temos que trabalhar somente no nível de steps, pois expressões não são permitidas a níveis de jobs ou do workflow como um todo. Vamos então criar um outro step e chamá-lo de Create URL.

Neste step, vamos executar uma Workflow Command, que são comandos nativos do GitHub Actions, que podem ser acessados com a sintaxe ::comando. No nosso caso vamos usar o comando set-env, que serve para criar uma nova variável de ambiente, a sintaxe é a seguinte: ::set-env name=<nome>::<valor> e ai poderemos utilizar as expressões de concatenação:

Veja que estamos concatenando ${{ env.MONGOKE_CONFIG_URL }} com ?v= e pegando os seis primeiros digitos de uma variável nativa de ambiente chamada GITHUB_SHA. Vamos adicionar este step após o login:

Agora vamos para o último passo, onde vamos executar o nosso comando, com uma pequena alteração, ao invés de utilizar a variável MONGOKE_CONFIG_URL, vamos trocar para a nossa nova variável MONGOKE_URL:

Nosso arquivo final será assim:

Agora podemos clicar no botão Start Commit e esperar o nosso action ser executado:

Acompanhando o workflow

Podemos acompanhar o nosso workflow na aba Actions:

Lembrando que workflows não executados nenhuma vez não vão aparecer na lista. Basta clicarmos no nome do workflow para podermos ver o que aconteceu:

Agora podemos observar no portal da Azure que nosso container foi atualizado:

E que também nossas URLs estão corretas:

Conclusão

Em 7 minutos automatizamos todo o processo de deploy da nossa aplicação para a Azure e, sem perceber, ganhamos muito tempo com uma ação simples e rápida que pode ser feita em poucos minutos!

Em outros artigos vamos explorar ainda mais os GitHub Actions para outras ferramentas e modelos de aplicação distribuída!

Não deixe de acompanhar mais do meu conteúdo no meu blog e se inscreva na newsletter para receber notícias semanais!

Há um tempo atrás, fiz um post em meu Medium onde falo tudo sobre o protocolo Iterator e sua interface de uso. Porém, além de APIs como Promise.finally, o ECMAScript 2018 trouxe para a gente uma outra forma de tratarmos os nossos iterators. Os async iterators.

O problema

Vamos nos colocar em uma situação bastante comum. Estamos trabalhando com Node.js e temos que ler um arquivo, linha a linha. O Node possui uma API para este tipo de função chamada readLine (veja a documentação completa aqui), esta API é um wrapper para que você possa ler dados de uma stream de entrada linha a linha ao invés de ter que fazer o parsing do buffer de entrada e quebrar o texto em pequenas partes.

Ela expõe uma API de eventos, que você pode escutar desta forma:

Imagine que tenhamos um arquivo simples:

Se rodarmos este código no arquivo que criamos, teremos um output linha a linha no nosso console. Porém, trabalhar com eventos não é uma das melhores formas de fazer código manutenível, pois eventos são completamente assíncronos e eles podem quebrar o fluxo do código, uma vez que eles são disparados fora de ordem e você só consegue atribuir uma ação através de um listener.

A Solução

Além da API de eventos, o readline também expõe um async iterator. Isso significa que, ao invés de fazermos a leitura da linha através de listeners no evento line, vamos fazer a leitura da linha através de uma nova forma de utilização da keyword for.

Hoje temos algumas opções de uso para um laço de repetição for, a primeira delas é o modelo mais comum, utilizando um contador e uma condição:

Também podemos utilizar a notação for ... in para leitura de índices de arrays:

No caso anterior, vamos ter como saída no console.log, os números de 1 a 6, porém se utilizarmos console.log(index) vamos logar o índice do array, ou seja, os números de 0 a 5.

Para o próximo caso, podemos usar a notação for ... of para pegar diretamente as propriedades enumeráveis do array, ou seja, seus valores diretos:

Perceba que todas as formas de utilização que descrevi são síncronas, ou seja, como fazemos para que possamos ler uma sequencia de promises em ordem?, imagine que tenhamos uma outra interface que nos retorne sempre uma Promise, que se resolve para a nossa linha do arquivo em questão. Para resolvermos essas promises em ordem, temos de fazer algo assim:

Porém, graças a magia dos async iterables (como o readline) nós podemos fazer o seguinte:

Perceba que agora estamos usando uma nova definição de for, o for await (const x of y).

For Await e Node.js

A notação for await é nativamente suportada no runtime do Node.js da versão 10.x. Se você está usando as versões 8.x ou 9.x então você precisa iniciar o seu arquivo Javascript com a flag --harmony_async_iteration. Infelizmente os async iterators não são suportados nas versões 6 ou 7 do Node.js.

Para podermos entender o conceito de async iterators, precisamos dar uma recapitulada sobre o que são iterators em si. O meu artigo anterior é uma fonte maior de informações, mas, em suma, um Iterator é um objeto que expõe uma função next() que retorna um outro objeto com a notação {value: any, done: boolean} onde value é o valor da iteração atual e done identifica se há ou não há mais valores na sequencia. Um exemplo simples, é um iterador que passa por todos os itens de um array:

Sozinho, um iterator não tem nenhuma utilidade prática, para que possamos tirar algum proveito dele, precisamos de um iterable. Um iterable é um objeto que possui uma chave Symbol.iterator que retorna uma função, a qual retorna nosso iterador:

Agora podemos utilizar ele normalmente, com for (const x of iterable) e teremos todos os valores do array sendo iterador um a um.

Se você quiser saber um pouco mais sobre Symbols, dê uma olhada neste outro artigo que escrevi só sobre o tema

Por baixo dos panos, todos os arrays e objetor possuem um Symbol.iterator para que possamos fazer for (let x of [1,2,3]) e retornar os valores que queremos.

Como é de se esperar, um async iterator é exatamente igual a um iterator, exceto que, ao invés de um Symbol.iterator, temos um Symbol.asyncIterator em nosso iterable e, ao invés de um objeto que retorna {value, done} teremos uma Promise que resolve para um objeto com a mesma assinatura.

Vamos transformar nosso iterator acima em um async iterator:

Iterando assincronamente

Podemos fazer a iteração de qualquer iterator de forma manual, chamando a função next():

Para que possamos iterar através do nosso async iterator, temos que utilizar for await, porém, lembre-se que a keyword await só pode ser usada dentro de uma async function, ou seja, temos que ter algo deste tipo:

Mas, assim como os iteradores assíncronos, não são suportadas no Node 8.x ou 9.x, para podermos utilizar um async iterator nessas versões, nós podemos simplesmente extrair o next dos seus objetos e iterar por eles manualmente:

Perceba que for await é muito mais clean e muito mais conciso porque se comporta como um loop comum, mas também, além de ser muito mais simples de entender, checa pelo final do iterador sozinho, através da chave done.

Tratando erros

O que acontece se nossa promise for rejeitada dentro do nosso iterador? Bem, como qualquer promise rejeitada, podemos pegar seu erro através de um simples try/catch (já que estamos usando await ):

Fallbacks

Algo bastante interessante dos async iterators é que eles possuem um fallback para Symbol.iterator, isso significa que você pode utilizar ele também com seus iteradores comuns, por exemplo, um array de promises:

Async Generators

Em grande parte, iterators e async iterators podem ser criados a partir de generators. Generators são funções que permitem que suas execuções sejam pausadas e retomadas, de forma que é possível realizar uma execução e depois buscar um próximo valor através de uma função next().

Esta é uma descrição muito simplificada de generators, a leitura do artigo que fala somente sobre eles é imprescindível para que você possa entender generators de forma rápida e mais profunda.

Async generators se comportam como um async iterator, porém, você deve implementar o mecanismo de parada manualmente, por exemplo, vamos construir um gerador de mensagens aleatórias para commits do git para deixar seus colegas super felizes com suas contribuições:

Veja que não estamos em nenhum momento retornando um objeto {value, done}, então o loop não tem como saber quando a execução terminou. Podemos implementar uma função desta forma:

Caso de uso

Para exemplificar de forma mais interessante, vamos construir um async iterator para um caso de uso real. Atualmente, o driver do Oracle Database para Node.js suporta uma API de resultSet, que executa uma query no banco de dados e retorna uma stream de registros que podem ser lidos um a um através do método getRow().

Para criarmos esse resultSet precisamos executar uma query no banco, desta forma:

Nosso resultSet possui um método chamado getRow() que nos retorna uma Promise da próxima linha do banco que deve ser trazida, isso é um belo caso de uso para um async iterator não é? Podemos criar um cursor que nos retorna este resultSet linha por linha. Vamos deixar um pouco mais complexo através da criação de uma classe Cursor:

Veja que o cursor recebe o resultSet que ele deve trabalhar e o armazena em seu estado atual. Então vamos alterar nosso método anterior para que retornemos o cursor ao invés do resultSet de uma única vez:

Desta forma podemos fazer um loop por todas as nossas linhas retornadas sem precisar de uma resolução de Promises individual.

Conclusão

Async iterators são extremamente poderosos, especialmente em linguagens dinâmicas e assíncronas como o Javascript, com eles você pode transformar uma execução complexa em um código simples, escondendo a maioria da complexidade do usuário.

Não deixe de acompanhar mais do meu conteúdo no meu blog e se inscreva na newsletter para receber notícias semanais!

Javascript: Entendendo Async Iterators was originally published in Training Center on Medium, where people are continuing the conversation by highlighting and responding to this story.

Promises são um conceito essencial do JavaScript. Elas estão presentes em praticamente todo o ecossistema da linguagem.

Promises são um padrão de desenvolvimento que visam representar a conclusão de operações assíncronas. Elas não eram nativas do JavaScript até o ES6, quando houve uma implementação oficial na linguagem, antes delas, a maioria das funções usavam callbacks.

Neste artigo vamos estudar a fundo o que é uma Promise e como podemos entender seu funcionamento.

Vamos usar uma ferramenta muito legal chamado Promisees criada pelo Nicolás Bevacqua para podermos visualizar a execução de nossas Promises em tempo real de forma visual.

Antes de começar, queria deixar um disclaimer de que, apesar de saber que um artigo no Medium deveria ter mais ou menos 7 minutos para não ficar chato, este artigo é bem profundo e explicativo, então eu vou tentar colocar tudo o possível sobre Promises aqui para servir de guia para outros que possam estar procurando!

História das Promises

Promises remontam à década de 70 — como você pode ver neste artigo — e eram chamadas de futures, deferred ou delays. Pelo artigo, elas são definidas como:

Construtos usados para sincronizar a execução de um programa em linguagens de programação concorrentes. Eles descrevem um objeto que atua como um proxy para um resultado que é, inicialmente, desconhecido devido a sua computação não estar completa no momento da chamada.

De acordo com o que vemos na Internet, no JavaScript, as Promises fizeram sua primeira aparição em 2007 em uma biblioteca chamada MochiKit . Depois outras bibliotecas como o Dojo e o jQuery adotaram a mesma especificação pouco tempo depois.

Por fim, para padronizar todas as implementações, o grupo CommonJS escreveu a especificação chamada Promises/A+ que visava ditar todas as regras necessárias para definir o que era uma Promise e sua interoperabilidade com outros sistemas.

No caso do NodeJS, nas primeiras versões, o runtime já implementava nativamente Promises, que foram removidas em favor de callbacks (que é a forma como conhecemos NodeJS no início), depois do lançamento do ES6 a plataforma implementou nativamente a funcionalidade de Promises que já estava implementada no V8 desde algum tempo antes. Isto porque o padrão ES6 já implementa o modelo A+, que descrevemos antes, de forma nativa, portanto a grande maioria dos browsers já permite o uso de Promises sem nenhum tipo de biblioteca externa.

Fluxo Assíncrono

O JavaScript por si só é tido como uma linguagem que tem que lidar com várias chamadas e execuções que não acontecem no momento que o programador executou o código, por exemplo, a leitura de um arquivo no NodeJS de forma síncrona:

Esta função é uma função síncrona, ou seja, quando a chamarmos, vamos pausar o que quer que esteja sendo executado e vamos realizar este processamento, depois vamos retornar o valor final. Desta forma estamos fazendo uma operação completamente síncrona. No nosso caso, vamos parar a execução do programa para buscar e ler o arquivo e depois vamos retornar seu resultado ao fluxo normal do programa.

Como queremos que nossas operações e nosso código rodem o mais rápido possível, queremos paralelizar o máximo de ações que conseguirmos. Ações de leitura de arquivos são consideradas lentas porque I/O é sempre mais lento que processamento em memória, vamos paralelizar a nossa função dizendo que queremos ler o arquivo de forma assíncrona:

Agora o que estamos fazendo é passando um callback para a função readFile que deverá ser executado após a leitura do arquivo. Em essência — e abstraindo muito a funcionalidade — o que a função readFile faz é algo assim:

Basicamente estamos registrando uma ação que vai ser executada após uma outra ação ser concluída, mas não sabemos quando essa ação será concluída. O que sabemos é apenas que em um momento ela será concluída, então o JavaScript utiliza o EventLoop — que não vamos cobrir neste artigo, mas vocês podem pesquisar aqui e aqui — para registrar um callback, basicamente o que estamos dizendo é: "Quando função X acabar, execute Y e me dê o resultado". Então estamos delegando a resolução de uma computação para outro método.

Uma outra opção

Muitas outras APIs nos fornecem uma outra opção ao se trabalhar com o fluxo assíncrono: os eventos.

Eventos são muito presentes no JavaScript, no front-end, quando escutamos por eventos de click em um botão com elemento.addEventListener ou no NodeJS quando podemos executar, por exemplo, um fetch que busca dados de uma API:

O problema com a API de eventos é que o código fica literalmente solto, então é difícil manter uma linearidade de pensamento porque o código vai ficar pulando de parte para parte.

Por que Promises?

Se já tínhamos uma implementação de funções assíncronas, por que houve a preocupação de criar todo um novo padrão para podermos ter exatamente a mesma coisa? A questão aqui é mais a organização do código do que a funcionalidade.

Imagine que temos uma função que lê um arquivo, após este arquivo ser lido ela precisa escrever em um outro arquivo e ai executar outra função assíncrona. Nosso código ficaria assim:

Veja que o código fica super complicado para ler… Isso é o que chamamos de callback hell

As Promises foram um passo seguinte para que pudéssemos melhorar um pouco a execução do nosso código. Primeiramente vamos melhorar nosso código anterior, podemos extrair as funções posteriores para outros blocos, melhorando um pouco a nossa visualização:

Agora o problema é outro, estamos encadeando nossas funções e fica muito difícil entender todo o fluxo porque temos que passar em várias partes do código. Com Promises, nosso código ficaria assim:

Veja que agora, apesar de nosso código não ter reduzido muito em tamanho, ele está mais legível, porque temos a implementação do then , de forma que conseguimos ver todo o pipeline de execução.

Promises

Promises, como já dissemos, definem uma ação que vai ser executada no futuro, ou seja, ela pode ser resolvida (com sucesso) ou rejeitada (com erro).

Há uma diferença entre lançar um erro e rejeitar uma promise. Lançar (dar um throw ) no erro, vai parar a execução do seu código, é o equivalente a darmos um return em uma função. Porém rejeitar uma Promise fará com que o código continue sendo executado posteriormente

A anatomia de uma Promise segue a seguinte API:

Como podemos ver, toda a Promise retorna um método then e outro catch , utilizamos o then para tratar quando queremos resolver a Promise, e o catch quando queremos tratar os erros de uma Promise rejeitada. Tanto then quanto catch retornam outra Promise e é isso que permite que façamos o encadeamento de then.then.then .

Para criarmos uma Promise é muito simples, basta inicializar um new Promise que recebe uma função como parâmetro, esta função tem a assinatura (resolve, reject) => {} , então podemos realizar nossas tarefas assíncronas no corpo desta função, quando queremos retornar o resultado final fazemos resolve(resultado) e quando queremos retornar um erro fazemos reject(erro) .

Estados de uma Promise

Uma Promise pode assumir quatro estados principais:

• Pending: O estado inicial da Promise, ela foi iniciada mas ainda não foi realizada nem rejeitada
• Fulfilled: Sucesso da operação, é o que chamamos de uma Promise realizada (ou, em inglês, resolved) — eu, pessoalmente, prefiro o termo resolvida.
• Rejected: Falha da operação, é o que chamamos de uma Promise rejeitada (em inglês, rejected)
• Settled: É o estado final da Promise, quando ela já sabe se foi resolved ou rejected

Uma Promise que está pendente (pending) pode vir a se tornar uma Promise resolvida com um valor, ou então rejeitada por um motivo (que é o erro). Sempre que qualquer um dos dois casos acontecer, o método then da Promise será chamado e ele será o responsável por verificar se houve um erro ou um sucesso, chamando o método resolve em caso de sucesso, ou reject em caso de falha.

É importante mencionar que o método catch é somente um alias para o segundo parâmetro de then . Ele torna o código bem mais legível, então é considerado uma boa prática

Encadeamento

O encadeamento de Promises (com then e catch ) é muito importante para entendermos o que está acontecendo, porque dependendo da forma como encadeamos nossas chamadas, vamos ter resultados diferentes.

Vamos tomar o seguinte exemplo:

Quando fazemos isto, estamos ligando tanto o bloco then quanto o catch na mesma Promise p , perceba que estamos passando dois parâmetros para a função then— ou então diretamente na Promise criada no segundo caso, não há diferenças. Vamos ter este mapa:

Vamos modificar um pouco o nosso código e fazer o bind do nosso then e catch separadamente:

Isso nos dá dois bindings diferentes para a mesma Promise, apesar da semântica ser um pouco diferente, o resultado ainda é o mesmo que temos acima, porém com duas ligações diferentes:

Agora temos o terceiro caso, onde criamos o encadeamento de um catch no próprio then — isto porque, lembre-se, todo o then e catch retorna uma outra Promise para nós — vamos modificar o nosso código:

Isto fará com que a ligação do catch seja feita na Promise retornada por then e não na nossa Promise criada originalmente:

Um catch para todos controlar

Essencialmente, tudo o que fizemos acima não tem muitas diferenças práticas, isto por conta de algo super importante que não acontecia nos callbacks.

Quando falamos de callbacks temos que pensar em funções externas. Um callback poderia aceitar uma função única que iria receber como parâmetro um objeto err e um data , que são respectivamente os erros ocorridos na função assíncrona que o chamou e os dados recebidos no caso de sucesso (muito próximo do nosso then e catch ), porém esta função só iria capturar os erros daquela execução, ou seja, para cada callback teríamos que ter uma nova função de recuperação e de tratamento de erros ou então teríamos que tratar cada erro em uma função separada.

Com Promises isso não acontece, isto porque, independente do tratamento que damos a Promise, ele sempre vai buscar o primeiro tratamento de erros disponível, em outras palavras, todos os erros irão cair para o primeiro catch que encontrarem. Vamos a um exemplo.

Temos uma função cara ou coroa, ela vai resolver a promise com sucesso se o valor de Math.random() — que te dá um número aleatório entre 0 e 1 — for maior que 0.5, caso contrário ela vai rejeitar essa Promise:

Colocamos um then e um catch simples, se for resolvida, vamos logar a mensagem no stdout se não, no stderr . Isso nos dá o seguinte mapa para um sucesso (quando tiramos um número maior que 0.5):

E vamos ter printado no console somente yay . Porque o then foi chamado já que resolvemos a Promise. Mas no nosso mapa anterior podemos ver que temos um catch ligado nele, isto acontece porque ligamos o catch no then , então ele computou que haveria uma chamada de tratamento de erros, mas como não houve uma rejeição ela não foi executada. Se colocássemos p.then e depois p.catch, ao invés de p.then.catch, teríamos o seguinte mapa de sucesso:

Veja que agora o catch não foi computado porque ele não está ligado no then , mas sim no p original. Da mesma forma em um erro teríamos somente o error() sendo executado:

Agora o que acontece quando temos uma série de ações que queremos tomar depois? Por exemplo:

Veja que aqui estamos executando 3 ações após a primeira Promise, a cada ação nós printamos na tela o que estamos fazendo e retornamos o mesmo valor para a próxima Promise — lembre-se que cada then retorna outra Promise, então todo o valor retornado dentro de um then é como se estivéssemos dando um resolve(valor) dentro de uma Promise — e por fim temos um handler de erro que deverá pegar todos os erros da primeira Promise e printar um no no console:

Em um fluxo de sucesso vamos ter todas as ações executadas e o nosso catch contabilizado mas não executado, nossa saída seria algo assim:

yay da ação 1
yay da ação 2
yay da ação 3

E para um fluxo de erro teríamos:

Com simplesmente um no no console, ou seja, ele pulou todos os then , e caiu diretamente no nosso handler de erro. O que acontece se colocamos um outro catch na jogada?

Veja que estamos declarando agora dois handlers de erro. O que deve acontecer é que, quando a Promise for rejeitada, ele deverá chamar o primeiro handler (erro1) e parar por ai, certo? Errado:

O que aconteceu aqui? Nosso catch erro1 foi executado, mas parece que todo o resto do fluxo seguiu normalmente! Lembre-se que "jogar" um erro é diferente de rejeitar uma Promise. O throw irá parar a execução do sistema, mas um reject irá manter o sistema sendo executado, por esta razão é possível ter múltiplos catch em uma Promise. Cada catch irá capturar o erro relativo às Promises anteriores, uma vez capturado, o valor que ele retornar será passado para a próxima Promise que executará normalmente.

No caso acima vamos ter a seguinte saída no console:

Primeiro catch
Error da ação 2
Error da ação 3

E em um caso de sucesso vamos obter a mesma saída que já obtemos anteriormente, porque não vamos cair em nenhum bloco catch . Isso é importante porque muitos pensam que o catch é universal, mas na verdade, quando encadeados em outros then , o primeiro erro que acontece consome o primeiro catch e assim por diante.

Agora, se tivéssemos feito algo deste tipo:

Veja que estamos separando o que é sucesso do que é erro, então o nosso mapa de erros seria algo assim:

E isso significa que iríamos printar ambos os erros no console:

Primeiro catch
no

Perceberam como a ordem do encadeamento importa? E neste caso:

Aqui vamos ter alguns casos específicos, se p falha, então a função erro1 e erro2 devem ser executadas, mas não erro3 de acordo com esse mapa:

Isto porque estamos criando um handler de erro acoplado à Promise original e outro que está acoplado ao resultado da execução posterior (os then ). Então nossa saída seria algo assim:

Eu pego todos os erros dessa promise
Eu pego somente os erros que aconteceram até a ação 1
Eu executo normalmente
Eu executo normalmente

Isto acontece pelo mesmo motivo que falamos antes, o primeiro catch é consumido e as demais funções executam normalmente. Agora, se a Promise p é resolvida, então sempre vamos ter um erro na acao1 — isto porque demos um throw dentro dela, e isso é o equivalente a dar um reject na Promise que este then retorna — e ai vamos ter outro mapa:

Veja que erro1 não é executado de maneira nenhuma, porque a Promise p foi resolvida com sucesso, o que deu o erro foi uma de suas execuções posteriores, a acao1 , e o catch com a função erro1 não está ligado neste then . Então teríamos a seguinte saída no console:

Estou rejeitando o valor, o catch a seguir deve tratar
Eu pego somente os erros que aconteceram até a ação 1
Eu executo normalmente
Eu executo normalmente

Perceba que as demais Promises de acao2 e acao3 continuam executando em todos os casos.

Promise.finally

O ES9, lançado em 2018, trouxe uma nova funcionalidade às Promises, o finally . De acordo com a especificação, este método sempre será executado, independente se a Promise foi resolvida ou rejeitada. Isto foi criado para manter a ideia do try/catch/finally que já existe há décadas em outras linguagens e pode ser muito útil em diversos casos.

Em um bloco padrão de try/catch/finally temos a seguinte estrutura:

try {
 // código executado
} catch (erro) {
 // irá cair aqui se o código executado jogar um erro
} finally {
 // essa parte sempre vai ser executada
}

O mesmo funciona para as Promises. Vamos a um exemplo:

No caso de um sucesso, vamos ter a seguinte saída do console:

yay
Eu sempre sou executado

Já no caso de um erro:

no
Eu sempre sou executado

Ou seja, é como se tivéssemos sempre alguém ouvindo a finalização de nossas Promises para sempre executar um trecho de código. O método finally já está disponível desde a versão 10.3 do NodeJS e na maioria dos browsers.

Settled

Um estado importante de comentarmos aqui é o estado Settled de uma Promise. Como já falamos antes, este estado é quando temos uma Promise completamente resolvida, que já recebeu seus valores de resolved ou reject, ou seja, é uma Promise que já "acabou".

Uma Promise neste estado já teve seus handlers then e/ou catch executados. A partir deste ponto dizemos que ela está terminada, agora, se no futuro adicionarmos outro handler, digamos, outro then , na mesma Promise, o que acontece?

Vamos analisar o fluxo desta Promise:

1. A Promise é criada
2. O handler then é adicionado
3. Após 2s a Promise recebe a resposta do resolve
4. A Promise executa o handler e é dada como settled
5. Um novo handler é adicionado

Promises que já estão com o estado definido como settled são resolvidas imediatamente após a adição posterior de um novo handler, ou seja, nosso handler tardio de multiplicação vai retornar na hora o valor 2000:

Promises de Promises

É possível para que uma Promise retorne outra Promise para ser resolvida, por exemplo, vamos imaginar que temos que pegar duas informações diferentes de APIs diferentes, mas uma depende da outra.

Quando retornamos uma Promise para outra Promise, só vamos ter a resolução completa do conjunto quando ambas as Promises entrarem no estado settled. Ou seja, se, dentro de uma Promise, chamamos outra Promise, a primeira só se resolverá após o retorno da segunda como settled:

O que acontece aqui é a Promise inteira só será resolvida após a execução do primeiro fetch e também do segundo fetch , que retorna uma Promise resolvida no último then . Vamos a outro exemplo mais simples.

Uma Promise que retorna outra Promise que pode ou não ser resolvida após 1s, usando nossa mesma função de moeda:

Veja como fica esta execução em tempo real:

Veja que o primeiro then fica amarelado, porque ele está esperando a segunda Promise (a que tem o setTimeout ) ser resolvido, isto significa que ele está bloqueado, na espera da segunda Promise. Quando a mesma retorna, todos os outros handlers são resolvidos instantaneamente.

Métodos de Promises

Além do then , catch e finally uma Promise também possui outros métodos estáticos muito úteis.

Promise.resolve e Promise.reject

Estes dois métodos são atalhos para quando queremos retornar uma Promise que sempre terá o mesmo valor, ou sempre resolvida, ou sempre rejeitada, de forma que não precisamos ficar criando todo o boilerplate de new Promise... .

Vamos imaginar que temos a seguinte Promise:

const p = new Promise((resolve) => resolve(1056))

Independente do que acontecer, a Promise sempre resolverá para o valor 1056. Ela nunca terá um catch e nunca lançará um erro… Então podemos simplesmente escrever assim:

const p = Promise.resolve(1056)

De forma similar podemos fazer com o reject :

const p = Promise.reject('Erro')

Promise.all

A ideia do método all é executar ações simultaneamente, ou seja, disparar uma série de Promises ao mesmo tempo e esperar pelo retorno de todas elas. Isto é muito útil quando, por exemplo, temos que pegar informações de várias APIs que não são relacionadas entre si.

Um exemplo mais real seria: "Buscar todos os dados de redes sociais de um usuário", podemos pegar todos os usuários desse cliente nas redes sociais e disparar um monte de Promises, uma para cada rede social e esperar a resposta.

O método Promise.all é justamente isso. Ele recebe um Array de Promises não resolvidas e inicia todas elas. Ele só vai terminar em dois casos:

1. Todas as Promises do array foram resolvidas
2. Pelo menos uma Promise foi rejeitada

Ou seja, é um método tudo ou nada, se todas as Promises tiverem sucesso, o método terá sucesso, porém no primeiro erro, o método te devolverá um erro.

Vamos ver este snippet de código (também presente no Promisees):

Criamos um array de várias Promises, cada uma delas resolve em um momento diferente, porém nenhuma delas tem uma propriedade b ou c então elas serão rejeitadas naturalmente, veja a animação:

Perceba que temos 3 new() ligados a um [all] , eles se resolvem em momentos diferentes, uma vez que todos são resolvidos, o método then é chamado, mas ele retorna um erro que rejeita a sequencia de Promises, nesse instante todo o método é finalizado e o array de Promises é dado como settled. Retornando o resultado do erro.

Vamos modificar o código para que elas passem:

Veja como o mapa fica agora:

Agora é bem mais claro de ver que o [all] espera todas as Promises se resolverem antes de chamar seu handler, no caso de sucesso, o Promise.all retorna um array com todos os resultados das Promises enviadas.

Vamos ver o que acontece no caso de uma dessas Promises ser rejeitada:

Perceba como podemos ver exatamente o funcionamento do Promise.all :

Quando a segunda Promise é rejeitada, todos os handlers são chamados imediatamente, ou seja, o método retorna o valor do erro da segunda Promise para o catch e ignora completamente a última Promise, ela ainda é executada, mas não tem seu valor consumido por ninguém.

Promise.race

O método Promise.race faz exatamente o que o nome diz, ele recebe um array de Promises, inicia todas elas, a que retornar Primeiro vai ser o retorno do método por completo. Ele é um caso especial do Promise.all onde, ao invés de esperar todas as Promises serem resolvidas, simplesmente retorna o primeiro resultado que obtiver. Veja este exemplo:

Temos dois arrays de Promises, um deles é resolvido em 4s e depois rejeitado em 8s, enquanto o outro é rejeitado em 2s e depois resolvido em 6s e 10s, vamos ver o mapa:

Perceba que, no primeiro caso, o método [race] aguarda duas Promises, enquanto o segundo aguarda 3. O primeiro tem sua Promise resolvida e ele já se torna verde, porque é o resultado que ele espera, então a segunda Promise (que é rejeitada) não é sequer consumida.

No segundo race (o que fica vermelho no final), temos uma Promise que é rejeitada logo de cara, então todas as demais Promises são ignoradas e o handler catch é chamado.

Async/Await

Não irei me estender demais sobre async e await por aqui porque já escrevi um artigo que fala sobre ele com mais detalhes. O que vou dizer aqui é somente uma desmistificação do que a maioria pensa sobre estas keywords.

Async e await são keywords que foram introduzidas no ES8 em 2017. Basicamente é um syntax sugar (uma firula de linguagem que foi adicionada somente para poder facilitar a escrita) do then e catch .

O motivo pela adição do async/await foi o mesmo da adição das Promises no JavaScript, o callback hell. Só que dessa vez tínhamos o Promise hell, onde ficávamos aninhando Promises dentro de Promises eternamente e isso tornava tudo muito mais difícil de se ler.

A proposta de funções assíncronas é justamente nivelar todo mundo em um único nível. Escrever um código assim:

async function foo () {
 if (Math.random() > 0.5) return 'yeah'
 throw new Error('ops')
}

É a mesma coisa que escrever isso:

const foo = new Promise((resolve, reject) => {
 if (Math.random() > 0.5) return resolve('yeah')
 reject('ops')
})

A diferença é que podemos deixar tudo no mesmo nível, ao invés de escrevermos:

foo.then((resposta) => { ... }).catch((erro) => ...)

Podemos fazer isto (desde que estejamos dentro de outra função async):

async function bar () {
 try {
    const resposta = await foo()
 } catch (erro) { throw erro }

Futuras implementações

O JavaScript é um padrão que está em constante mudança. Portanto já existem novas ideias e implementações para novos métodos de Promises, o mais legal é o allSettled .

Promise.allSettled

Este método veio para sanar um grande problema com o Promise.all . Em muitos casos reais, nós queremos executar várias Promises de forma paralela e trazer o resultado de todas elas, e não só o erro ou então só o array de sucessos, nós queremos tanto os erros, quanto os sucessos.

Atualização: A proposta do allSettled foi implementada na versão 12 do Node.js e já está disponível para uso nas últimas versões LTS a partir da 12 (14 e 16), obrigado ao @KuryKat pelo aviso: https://node.green/#ES2020-features--Promise-allSettled

Vejamos o exemplo — que está também na documentação — sobre o motivo desta proposta:

Este é um problema comum com o Promise.all , quando queremos pegar o resultado de todas as Promises, temos que fazer uma função de reflexão, que nada mais faz do que atribuir um handler para cada uma das Promises no array e jogar isso tudo dentro do all . Desta forma estamos sobrescrevendo o comportamento original da Promise pelo nosso próprio e retornando para cada valor um objeto com as descrições do que aconteceu.

A proposta pretende criar um método allSettled para abstrair a função reflect :

Ambos os casos irão nos dar um array de objetos no final com esta assinatura:

[
  { status: 'resolved', value: 'valor da resolução' },
  { status: 'rejected', reason: 'mensagem de erro' }
]

Para mais informações veja a página da proposta.

Conclusão

O Objetivo da escrita deste artigo não foi somente para entrar mais a fundo em Promises como um todo, mas sim devido a uma grande dificuldade que notei em vários programadores (até mesmo experientes, incluindo eu mesmo) com o fluxo assíncrono do JavaScript.

Não deixe de acompanhar mais do meu conteúdo no meu blog e se inscreva na newsletter para receber notícias semanais!

Espero que, com este artigo, possamos entender de uma vez por todas o que são Promises e o que elas significam e qual é a importância desta adição para a linguagem e porque todos deveriam saber Promises ao invés de callbacks.

Veja a segunda parte deste artigo aqui!

Se você viu algum erro, tem alguma sugestão ou quer adicionar algo no artigo, fala comigo através de qualquer uma das minhas redes sociais em http://lsantos.dev :D

Edição 09/05/2019

Para complementar este artigo, fui chamado pela Digital Innovation One para fazer um webinar sobre Promises, onde me baseei no que aprendemos aqui e mostrei de forma prática! Recomendo muito para acompanhar e acrescentar ao estudo:

Referências

• https://github.com/tc39/proposal-promise-allSettled
• https://braziljs.org/blog/promises-no-javascript/
• https://en.wikipedia.org/wiki/Futures_and_promises
• https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Promise
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#Run-to-completion
• https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Guide/Usando_promises
• https://ponyfoo.com/articles/es6-promises-in-depth
• https://nodejs.org/dist/latest-v8.x/docs/api/util.html#util_util_promisify_original
• https://medium.freecodecamp.org/es9-javascripts-state-of-art-in-2018-9a350643f29c

Entendendo Promises de uma vez por todas was originally published in Training Center on Medium, where people are continuing the conversation by highlighting and responding to this story.

O entrevistado desta vez será um dos co-organizadores do meetup do Training Center em SP, Luiz Felipe Limeira!

Um pouco sobre você…

Sou formado em Ciências da Computação desde 2015 e trabalho como desenvolvedor desde 2011, atualmente trabalho no Pagar.me utilizando Node.js no desenvolvimento de serviços voltados para pagamentos de mundo físico. Fora do âmbito profissional, eu tenho prezado bastante por minha qualidade de vida, então eu tento me manter longe de computadores e fazer coisas que eu gosto, como andar de patins, longboard, viajar, ver séries no Netflix e outros, mas também reservo tempo para frequentar meetups, escrever artigos e ajudar na organização do meetup do Training Center em SP.

Como você conheceu a área que você trabalha hoje?

Se eu me lembro bem, tudo começou quando meu primo começou a fazer faculdade de design gráfico e me mostrava uns códigos estranhos que serviam para fazer sites.

Não lembro ao certo quantos anos eu tinha, mas com mais ou menos 15 anos, apareceu um trabalho de história que o professor pediu para colocar em um blog ou site, e o link para todos os trabalhos deveriam ficar centralizados em um “portal”, eu resolvi ficar responsável por fazer essa página para a sala e lembrei dos códigos estranhos. Com o Google como meu guia eu fui desenvolvendo a página com um monte de imagens de fundo e os links (rsrsrs), como podem imaginar, ficou bem feia.

O trabalho não foi para o ar, pois trocaram o professor de história, e obviamente ele achou melhor não publicar os trabalhos por conta de direitos de imagem e autorais (quem nunca copiou texto da internet para trabalhos escolares?). Esse foi meu primeiro contato com desenvolvimento, o que me ajudou quando eu entrei na ETEC para cursar Informática para Internet.

Depois disso você continuou seus estudos na área? Como foi todo o processo para, de fato, conseguir o primeiro trampo e quais dicas você daria para uma pessoa iniciante?

Sim… Depois disso, eu gostei de ter feito o site, e tinha muita vontade de fazer Ciências da Computação, mas meu desempenho em matemática no colégio me fazia ter muitas incertezas, resolvi que não teria muita capacidade para esse curso, e no final do primeiro ano do colegial eu resolvi que queria fazer ETEC de Informática para Internet, que seria para eu ter uma base se era aquilo mesmo que eu iria fazer.

Durante o curso, um professor chamado Pirola, chamou todos para o auditório, como tínhamos dificuldades na parte de exatas do curso — e, consequentemente, na matéria dele — Ele explicou a importância de exatas para a área e as coisas que eram possíveis de serem feitas. Aquela palestra mudou minha vida, dei mais foco para exatas, minhas notas melhoraram na escola e resolvi que eu era sim capaz de fazer Ciências da Computação.

Na ETEC não me dei muito bem nas matérias de design e front-end e esse foi o sinal definitivo de que eu queria focar em ser desenvolvedor back-end (obs: na época o front-end era muito ligado a parte de design, usava muito flash também, hoje em dia eu gosto de mexer com front-end).

Aquela palestra mudou minha vida, dei mais foco para exatas, minhas notas melhoraram na escola e resolvi que eu era sim capaz de fazer Ciências da Computação — Luiz Felipe

Assim que eu terminei a ETEC e o ensino médio, não consegui pagar a faculdade logo de cara e tentei em algumas faculdades públicas, mas não passei, não tinha trabalho na época dos vestibulares, em janeiro eu recebi uma ligação de que o tio de uma amiga precisava de um web designer — esse foi meu primeiro emprego — trabalhava para pagar cursos de desenvolvimento com meus pais me ajudando a pagar metade, felizmente pude contar com a ajuda deles, pois, na época, ganhava pouco trabalhando como auxiliar de web design, até hoje não conheci o web designer da empresa rs (agora é engraçado relembrar, mas era triste).

Depois de um ano apenas trabalhando e fazendo cursos, aí sim seria possível começar a faculdade, e assim foi, com meu pai pagando metade e eu a outra metade até o terceiro ano da faculdade, depois de trocar de emprego duas vezes, eu já conseguia pagar a minha faculdade sozinho do terceiro ano em diante. As matérias exatas deram trabalho, mas consegui superá-las sem maiores traumas rs.

Conheça pessoas, não se limite ao conhecimento que você vivencia no seu serviço ou escola — Luiz Felipe

Acredito que grande parte do que eu consegui, foi por ter amigos… Meu primeiro emprego foi por indicação, o segundo foi por indicação de um amigo da faculdade… Uma dica que posso deixar quanto a isso é, conheça pessoas, não se limite ao conhecimento que você vivencia no seu serviço ou escola, pesquise muito no Google (ele foi o meu maior companheiro durante toda a minha caminhada) e algo que eu aprendi recentemente: não tenha medo de perguntar e errar, você sempre vai precisar aprender, e errar faz parte do processo, por isso erre. E você precisará saber como fazer da forma correta após o erro, então pergunte (para amigos, colegas de trabalho, Google, não importa quem ou o que, mas pergunte), pois assim você irá aprender. Essas são as minhas dicas.

Não tenha medo de perguntar e errar, você sempre vai precisar aprender, e errar faz parte do processo — Luiz Felipe

Você disse que uma das coisas mais importantes é conhecer pessoas. Quais seriam suas dicas para encontrar e conhecer mais pessoas?

Bom, acho que o principal é a pessoa estar aberta a conhecer novas pessoas, não ter medo de ir falar com alguém, e isso me travou um pouco quando comecei a ir em eventos e meetups, grande parte das pessoas que eu conheci nesses 2 últimos anos foi por conta das comunidades de desenvolvimento; Na minha opinião, esse é o melhor fruto que levamos dos eventos, mas temos que tomar cuidado para não sermos pessoas egocêntricas, estarmos sempre abertos a adquirir conhecimento e filtrar o mesmo, por que desenvolvedor por si só já é egocêntrico, nós queremos valorizar nosso conhecimento e muitas vezes o ego fala mais alto, isso é comum em comunidades de desenvolvimento.

O principal é a pessoa estar aberta a conhecer novas pessoas, não ter medo de ir falar com alguém — Luiz Felipe

Acho que, nesse caso, a empatia é a melhor coisa. Não responder algo como se fosse muito óbvio (o que é muito comum) é fácil, pois todos já tivemos dificuldades que pareciam fáceis para pessoas mais experientes.

Na sua opinião o que seria a comunidade ideal? O ambiente ideal de cooperação, e como podemos chegar lá?

Acho que uma comunidade em que as pessoas colocam mais a mão na massa, programação é prática, as empresas pedem experiência, comunidade é o lugar perfeito para dar isso para as pessoas.

Outro ponto é ter empatia e menos ego, as pessoas esquecem que já foram iniciantes, e que algumas pessoas têm mais dificuldade que as outras em algumas coisas, já vi muitas respostas ruins, já vi muitas respostas boas, acho que o primeiro passo é as pessoas deixarem de se colocar a cima das causas apenas para alimentarem seus egos ou se beneficiarem.

Para mim essas pessoas só alimentam mais e mais a síndrome do impostor das outras pessoas. Se explicarmos as dúvidas de forma fácil, sem valorizar ou querer mostrar que sabemos falar bonito, fica muito mais fácil atingir o objetivo principal, ajudar uns aos outros. Ou pelo menos esse deveria ser o motivo principal.

Você participa de muitas comunidades, isso é um fato, qual foi o momento ou a ação mais importante que aconteceu contigo durante toda essa participação?

Acho que o mais marcante foi quando eu comecei a participar de comunidades, foi um choque, não entendia mais da metade das coisas que eu ouvia, me sentia muito atrasado, senti que todos os anos anteriores eu estava parado, e isso vendo agora, foi bem ruim para minha saúde, mas me fez evoluir muito e me fez correr atrás das coisas.

Mas o momento mais importante foi quando eu percebi como a tecnologia tem um poder real de mudar a vida das pessoas, como a tecnologia consegue prover a chance das pessoas mudarem o meio em que elas vivem e ultrapassarem as próprias barreiras, nessa caminhada já vi várias pessoas que provaram isso, e o projeto Juntos na TI foi um marco forte que me fez ter certeza disso.

Você comentou sobre ansiedade e síndrome do impostor. Na sua opinião, esses seriam os piores problemas de desenvolvedores atuais? Quais são suas dicas para lidar com estes problemas?

Na minha opinião esses, juntamente com a questão do ego e falta de empatia, são os maiores problemas, todos esses pontos juntos tornam o ambiente para quem está começando muito nocivo. Temos que parar de dizer o que as pessoas devem ou não fazer ou usar, e começar a falar sobre soluções, deixar de criar regras, e começar a deixar livre para a galera testar, errar e aprender. Esse é o ciclo do aprendizado.

Temos que parar de dizer o que as pessoas devem ou não fazer ou usar, e começar a falar sobre soluções — Luiz Felipe

Quando você cria um ambiente de disputa de ego, quem está observando acaba vendo muita coisa que é passada como o certo e não sabe para onde ir, assim surge a ansiedade e síndrome do impostor. Porque você está estudando HTML e CSS, aí alguém fala que você precisa aprender Angular, aí alguém fala que angular não presta e que você tem que aprender React, isso é muito prejudicial e as pessoas acabam não respeitando o tempo de aprendizado. Dessa forma as pessoas acham que precisam ter o equivalente a 1 ano de experiência em 1 mês.

Para mim está tudo atrelado…

Qual seria o ambiente de trabalho ideal para você?

O ambiente de trabalho ideal para mim é aquele em que todos são ouvidos, aquele em que existe respeito e oportunidade para todos crescerem, e principalmente que exista equilíbrio entre sua vida profissional e pessoal, não adianta ser o melhor lugar mas não conseguir pagar suas contas. Ame o seu trabalho e onde trabalha, mas não trabalhe apenas por amor.

Para mim, o ambiente de trabalho envolve tudo isso, porque se você não está bem na sua vida pessoal, dificilmente vai conseguir agregar para que o ambiente profissional esteja bom.

Vale deixar claro que também não da para trabalhar apenas por dinheiro sem pensar no ambiente profissional no qual está inserido, pois esse ambiente pode ser ruim o suficiente para influenciar na sua vida pessoal. Coisas como estresse, desrespeito, falta de reconhecimento e falta de espaço para se expressar, podem facilmente influenciar suas relações na vida pessoal.

Acho que nossa área permite achar essa balança. Existe os dois extremos, mas existe bastante lugar (principalmente nos grandes polos tecnológicos) que permite essa balança para todos os níveis de profissionais.

E quais são as skills necessárias para um profissional da sua área?

Acho que falar skills necessárias seria criar uma regra desnecessária, a área é tão ampla e temos tantas pessoas que conseguiram de diferentes formas, o básico é gostar do que faz e correr atrás, de resto, até soft skills básicas como por exemplo trabalhar em equipe, eu já vi pessoas que não tinham e mesmo assim estão na área.

Acredito que para progredir na área é importante saber se vender, não ter medo de falar e mostrar o que sabe, ter soft skills como trabalho em equipe, uma comunicação não violenta, saber dar (e receber) feedbacks e não aceitar as coisas como estão, sempre pensar em melhorar.

Acredito que para progredir na área é importante saber se vender, não ter medo de falar e mostrar o que sabe — Luiz Felipe

Como desenvolvedor, é interessante ter a base, pois tem devs que sabem muitas ferramentas e frameworks, mas encontram dificuldades em algum momento com algoritmos, lógica de programação, dependendo da linguagem pode ter dificuldade com conceitos de OO, ou outros paradigmas.

Na minha opinião isso vai muito de encontro com “não pular steps”, respeitar o tempo de aprendizado. Lógico, nem todo mundo tem esse tempo ou condições financeiras para seguir passo a passo, por isso é importante recuperar isso em algum momento.

E quais são os principais desafios e recompensas dessa área?

Para mim os desafios mais legais ultimamente é a parte de negócio, não tem como você pensar em melhorar seu código e seu software, sem pensar no negócio, quando eu comecei a ligar mais e entender melhor sobre o assunto minha cabeça mudou, acho que isso é legal no desenvolvimento, nossa cabeça tem que estar sempre mudando e se adaptando.

É uma vida de estudos, é difícil parar, mas sempre lembrando que dá para estudar e aprender coisas novas sem prejudicar a saúde, aprender as coisas no devido tempo.

As principais recompensas, na minha opinião, são os produtos e os projetos que podemos fazer, ter a sensação de realmente estar fazendo algo e mudando as coisas; Outro ponto é que essa área permite uma liberdade incrível, tenho visto muitas pessoas mudando a vida delas, mudando de país, mudando o status social, a tecnologia é uma ponte e uma ferramenta poderosa para pessoas de baixa renda melhorarem de vida.

Você pensa em mudar de área? Se não, por que um profissional deveria se tornar um Dev Backend?

Nunca pensei em mudar de área, já pensei se no futuro eu pretendo mudar de responsabilidades, pensando na questão de carreira em Y, virar um tech lead ou virar um especialista, mas não em um futuro próximo, quero me aperfeiçoar em alguns aspectos para depois pensar nisso. Me vejo programando durante toda minha carreira, talvez menos ou mais, mas ainda sim programando.

Me vejo programando durante toda minha carreira — Luiz Felipe

Quanto a questão de ser desenvolvedor back-end, eu gosto muito dessa função, onde eu trabalho atualmente existem diversas funções que podemos desempenhar e uma fácil migração para elas, lá possui desenvolvimento back-end, front-end, mobile, baixo nível e outros, então se surgir alguma curiosidade, necessidade ou fizer sentido para o produto, me vejo explorando novas tecnologias e responsabilidades sim, acho interessante essas oportunidades.

Seguindo nessa linha, eu não acho que um(a) profissional deveria se tornar um(a) dev back-end, acho que um(a) dev deve procurar a função que mais lhe agrada e proporciona uma satisfação profissional, talvez se permitir conhecer novas coisas e então escolher, oportunidade para todas as áreas que eu citei não faltam.

Estudando e evoluindo fica bem tranquilo essa questão de experimentar novas responsabilidades, eu por exemplo não me sinto muito a vontade trabalhando como desenvolvedor front-end no momento pois sinto que não tenho as skills necessárias agora.

Finalizando…

Se você gostou desse post temos uma sessão no blog só pra eles, não esquece de dar um like e compartilhar! :D

Siga o Training Center no Twitter para se manter atualizado(a) sobre nossas novidades em @trainingcentr, Se quiser entrar em contato com o Luiz, veja o Twitter dele também!

Entre no nosso Slack para participar das decisões desse projeto e também para ver gifs engraçados! Conheça nossas iniciativas.

Como é trabalhar como desenvolvedor backend, por Luiz Felipe Limeira was originally published in Training Center on Medium, where people are continuing the conversation by highlighting and responding to this story.

Depois de algum tempo fora do ar, volto para apresentar a vocês um mistério, na verdade, nem tanto mistério, mas um tipo primitivo do Javascript que já existe há um tempo, mas nunca ficamos sabendo deles. Os Symbols.

Symbols? É de comer?

Symbols são um tipo primitivo do Javascript desde o ES6, mas eles já existiam antes disso. Symbols são usados para definir valores chaves para o funcionamento da linguagem há muito tempo, mas eles não eram acessíveis por ninguém, somente pelo próprio runtime e pelo interpretador. O que mudou foi que o ES6 tornou possível que nós, meros programadores, pudéssemos acessar esses tipos.

Symbols são caracterizados como uma espécie de "metaprogramação", que foca principalmente em poder acessar aspectos do core da linguagem. Podemos criar um Symbol dessa forma:

Perceba que não usamos nenhuma keyword new para definir um Symbol. Isto porque eles não são instâncias de nada, na verdade, se tentarmos fazer algo deste tipo:

Vamos ter um TypeError na nossa cara.

Symbols podem ter uma descrição para propósitos de debugging, então podemos fazer algo assim:

Ok, entendemos como podemos criar um, mas o que eles são de verdade? Symbols são tipos imutáveis nativos, assim como números ou strings. Mas temos que notar algo diferente, Symbols são únicos, diferentemente da maioria das primitivas que temos por ai.

Por serem únicos, ao compararmos eles, vamos obter resultados bastante interessantes:

Isto acontece porque cada símbolo tem um identificador único que não pode ser alterado, e é este identificador que faz a comparação entre eles. Da mesma forma, se utilizarmos typeof Symbol() ou typeof Symbol('desc') vamos sempre obter symbol .

Symbols são acessíveis de três formas que vamos explorar mais abaixo, mas tenha em mente algumas informações importantes:

• Symbols são acessíveis entre realms, por realm queremos dizer contexto, por exemplo, sua página é um contexto de document enquanto, dentro dela, podemos ter um <iframe> com um contexto/realm diferente.
• Você pode registrar Symbols globais e acessa-los por entre esses contextos também
• Uma das classes de Symbols é chamada de "Well-Known", eles existem entre realms, mas não são acessíveis no registro global de Symbols

"Runtime-wide" — Acessível pelo runtime

Existem duas formas que você pode utilizar para adicionar Symbols no escopo do runtime do sistema, ambas são através de métodos existentes dentro das APIs do próprio Symbol, o primeiro éSymbol.for(chave) .

Basicamente o que este método faz é verificar se existe um Symbol no registro global que seja associado a esta chave, se existir, ele é retornado, se não, ele é criado e retornado. Então vamos estudar um pouco as chamadas:

Veja que arranjamos um jeito de buscar os símbolos, mesmo eles sendo únicos. Isto acontece porque o registro global de Symbols mantém uma chave para cada Symbol criado, e isto é o identificador que podemos utilizar para encontrar esses valores neste escopo.

Note somente que, quando criamos uma "chave" usando Symbol.for('chave') , este valor se torna também nossa descrição.

Outra coisa importantíssima de se notar é que Symbols é o mais global que você vai chegar de qualquer outro tipo de variável global, porque além de eles serem acessíveis no seu código e no seu "realm" eles também estão disponíveis em contextos alheios. Então tome muito cuidado ao criar Symbols usando nomes genéricos como "user", "sort" e coisas do tipo, porque você pode acabar sobrescrevendo um valor importante do sistema.

Symbol.keyFor

De forma análoga, podemos encontrar a chave que foi associada a um Symbol através do método Symbol.keyFor(symbol) que, dado um Symbol criado previamente, vai nos retornar a chave associada a ele:

Dizer "Runtime-wide" significa simplesmente dizer que vamos poder acessar estes Symbols entre contextos, mais ou menos assim:

Veja que podemos acessar o mesmo Symbol de dentro de outra window presente no iframe.

"Well-known" — Os originais

Well known, traduzido, significa "Bem conhecido", mas, na verdade, esses Symbols não tem nada de conhecidos. Eles só são chamados assim porque fazem parte do core da linguagem, são built-ins. Antes do ES6, nenhum desses Symbols eram expostos, mas agora podemos brincar com eles.

Um grande exemplo foi utilizado em outro artigo sobre iterators que escrevi. Ele é utilizado para definir o método@@iterator em objetos que são aderentes ao protocolo de iteração. Além deste existe uma lista de Well-Known Symbols na MDN, muitos deles são bastante conhecidos pela gente como o replace ou o match .

Symbol.match

De acordo com a documentação, podemos setar o Symbol.match em expressões regulares para false , de forma que faremos elas se comportarem como strings literais quando estamos comparando uns com os outros (principalmente na hora de usar métodos como startsWith , endsWith e includes ):

Ou, podemos simplesmente usar o toString() que temos o mesmo resultado:

Outros usos legais destes Symbols podem ser encontrados aqui.

Acesso global

Well known Symbols são únicos, mas são compartilhados entre contextos, mesmo que eles não sejam acessíveis através do registro global que comentamos acima, vamos usar o mesmo código:

No entanto não podemos fazer isso:

Iterando por Symbols

Um uso interessante deste tipo é que eles podem ser usados como chaves de objetos, mais ou menos dessa forma:

Ao executarmos console.log(foo) ou qualquer coisa do tipo, vamos obter a representação em string desse objeto, já que os consoles estão inteligentes o suficiente para buscar essa informação. No entanto, se rodarmos Object.keys(foo) vamos ter somente ['propriedade'] . Isto porque o método keys de Object ignora completamente os Symbols. O mesmo vale para JSON.stringify , que vai simplesmente nos retornar {"propriedade": "legal"} .

Podemos ir ainda mais longe tentando usar um for ... in , ou até um Object.getOwnPropertyNames(foo) , mas todos eles vão ignorar os Symbols. Se você quiser realmente buscar esses valores, você precisa saber o que está procurando. Existe um método próprio para iterar por Symbols em um objeto, que é o Object.getOwnPropertySymbols . Se executarmos o trecho abaixo, vamos ter uma lista de todos os Symbols que criamos e poderemos iterar por eles, mais ou menos dessa forma:

Casos de uso

Até aqui só falamos muito sobre Symbols, mas para que raios você vai usar essa coisa!?

Temos alguns casos mais comuns que vou explicar por cima:

• Conflito de nomes: Neste caso podemos tirar proveito da natureza única do Symbol para evitar nomes repetidos em chaves de objetos, assim como fizemos no exemplo anterior.
• Privacidade: Se estamos criando um framework ou uma lib que precisa de algumas propriedades bem seguras, podemos tirar proveito de que nenhuma propriedade iterável que é largamente conhecida chega a iterar por Symbols, então podemos criar um objeto de configurações (ou metadados), por exemplo, e colocar vários Symbols por lá para definirmos nossas diretrizes de operação. Basta que você itere por ela usando Object.getOwnPropertySymbols .
• Constantes: Geralmente usamos uma string ou número para definir uma constante, por exemplo, o nível de um log, que pode ser definido como log.levels = { INFO: 'info', DEBUG: 'debug' } mas isso não os torna realmente globais seguros, porque podemos criar outros valores iguais e, ao invés de usar nossa função como log(log.levels.DEBUG, 'mensagem') podemos simplesmente fazer log('debug', 'mensagem') . Então podemos utilizar Symbols como log.levels = { INFO: Symbol('info'), DEBUG: Symbol('debug') } para prevenir isso

Em suma, Symbols são uma ótima maneira de atrelar propriedades em objetos de uma forma simples, ou então de criar diretrizes que seu programa deve seguir por baixo dos panos.

Se eu for ficar falando de todos os casos de uso de Symbols, provavelmente este artigo ficará imenso, então vou me ater a um último caso de uso que merece um pouco de explicação.

Definir protocolos e Hooks

Este é o maior caso de uso e, com certeza o mais legal de todos. Hoje, muitas libs populares utilizam protocolos sobre os quais alguns objetos devem aderir (como você pode ver aqui), não precisamos ir muito longe, o próprio Symbol.iterator é um protocolo a qual todos os Arrays aderem, e isto define que o objeto pode ser iterado.

Basicamente, ao executar um for ... of o Javascript faz uma checagem se Object[Symbol.iterator] existe, se sim, então parabéns, você tem um iterador, se não, você não pode iterar por esse objeto.

Vamos usar um caso mais interessante, se quisermos criar um protocolo que diz de qual forma um objeto deve ser transformado em string para ser printado na tela (basicamente o que o toString() faz). Podemos criar um Symbol.for('object.upper') e colocar este Symbol em qualquer um dos nossos objetos:

O exemplo anterior não irá funcionar porque não implementamos a lógica no console e nem no object.keys para olhar o valor de obj[Symbol.for('object.upper')] e printar tudo em maiúsculo, mas deu para entender a ideia. Uma implementação disto para o console seria algo assim:

Nada nos impede de adicionar uma função em um Symbol dentro de um objeto, criando o que é chamado de hook, funções que executam em determinadas partes do código respondendo a determinados métodos. Podemos, por exemplo, alterar o comportamento de como o console itera e inspeciona objetos por uma função própria, que é chamada sempre que o objeto é convertido para string.

Conclusão

Symbols são obscuros e achar uma utilidade para eles é realmente muito complicado, provavelmente ninguém vai ter que se preocupar em utilizar ou mexer em Symbols tão cedo.

No entanto, o entendimento que o Symbol proporciona para o programador acerca do funcionamento da linguagem é fora do normal. Apenas entendendo os iterators, somos capazes de deduzir como loops como for e for ... of funcionam sem precisar de muito esforço. Tornando nosso código muito mais interessante.

Não deixe de acompanhar mais do meu conteúdo no meu blog e se inscreva na newsletter para receber notícias semanais!

Javascript Symbols: Decifrando o mistério was originally published in Training Center on Medium, where people are continuing the conversation by highlighting and responding to this story.