hmh - Calculando horas com JavaScript

hmh - How many hours? foi uma ferramenta que eu resolvi criar, pois precisava fazer alguns cálculos com horas, mas não achei nada que eu pudesse usar, assim, “a toque de caixa”.
O projeto está no GitHub, nesse link. Quer saber como foi desenvolvido, desde a ideia, os testes até a publicação? Então vem comigo que eu te mostro :D

O problema

O que me motivou a criar a ferramenta foi: eu precisava calcular, de forma fácil, as horas que eu estava trabalhando em algum projeto. Eu deixava o tempo anotado em algum lugar - pois nem sempre a tarefa era finalizada de uma vez, às vezes era necessário começar outra sem terminar a primeira - e depois eu precisava calcular o tempo total que eu gastei nessa tarefa.

Isso ajuda pra que você saiba exatamente quanto tempo gasta para fazer cada coisa, ficando mais fácil “orçar” quando tempo você irá precisar para fazer algo parecido futuramente.

Necessidade

O que eu precisava, naquele momento, era de:

  • uma forma onde eu pudesse entrar com um horário inicial e um horário final, e saber quanto tempo foi gasto nesse meio tempo;
  • uma forma de somar esses intervalos, para saber o tempo total gasto na tarefa;
  • uma forma de saber quanto tempo por dia eu ainda precisaria trabalhar dentro da sprint (sim, usando SCRUM) para saber se eu teria horas sobrando para encaixar alguma outra tarefa, ou se eu já tinha esgotado meu tempo.

Com essas informações, ficaria mais simples para que eu pudesse planejar as próximas sprints com uma precisão maior.

A solução

Antes de fazer a lib, pesquisei para ver se encontraria algo já pronto que eu pudesse utilizar, e talvez até colaborar no desenvolvimento. Enfim, não achei nada que resolvesse o que eu precisava de forma fácil (inclusive, se você souber de alguma ferramenta que faça isso, deixe nos comentários que eu preciso saber :D).

Assim surgiu o hmh! :grin:

O nome

O nome é uma abreviação para How many hours?, pois eu precisava saber quantas horas eu gastei, e quantas horas eu tinha disponível. Inicialmente eu pensei em fazer uma [CLI], pois como eu fico o dia todo com o terminal aberto, seria bem simples simplesmente digitar as horas ali e ver o resultado, passando alguns parâmetros para a CLI.

Mas depois eu percebi que isso também poderia ser usado para outras coisas, então faria mais sentido criar uma lib com toda a lógica que eu precisava, e então criar a CLI, consumindo essa lib.

Você pode ver o código da lib aqui e da CLI aqui.

Como a lib funciona?

O uso da lib é bastante simples: para instalar, execute:

1
npm i --save hmh

Então é só usar! A lib tem 4 métodos: sum, sub, diff e div, que servem para os propósitos que citei acima.

O retorno desses métodos vai ser sempre um horário, um valor em horas e minutos.

Exemplo:

Imagine que você trabalhou um tempo em um projeto, e quer somar todo esse tempo. Só precisa passar o tempo por parâmetro para o método sum:

1
console.log(hmh.sum('1h 20m 15m 2h 40m')) // '4h 15m'

E o resultado é a string '4h 15m'. Se você quiser ver o resultado somente em minutos, passe minutes como segundo parâmetro:

1
console.log(hmh.sum('1h 20m 15m 2h 40m', 'minutes')) // '255m'

O método sub funciona da mesma forma, mas ele subtrai valores.

O método diff mostra a diferença entre duas horas. Imagine que você começou a trabalhar em uma tarefa às 8h15m da manhã e parou às 11h30m. Quanto tempo se passou?

1
console.log(hmh.diff('8h 15m', '11h 30m')) // '3h 15m'

E ele mostra o resultado! Para ver em minutos, mesmo esquema dos outros métodos: como último parâmetro, passe minutes:

1
console.log(hmh.diff('8h 15m', '11h 30m', 'minutes')) // '195m'

E por último, o método div. Digamos que você trabalha em um projeto, e vende horas de manutenção. Você ainda tem 7h para mexer nesse projeto nos próximos 4 dias. Quantas horas por dia você pode trabalhar para completar as 7h? Simples: é só dividir 7h em 4 dias:

1
console.log(hmh.div('7h', 4)) // '1h 45m'

Você pode trabalhar 1h 45m por dia =)

Command Line Interface

Mas isso seria mais útil se eu pudesse usar isso direto no terminal. Por isso eu fiz o hmh-cli, que também é bastante simples de usar!

Primeiro de tudo, instale globalmente:

1
[sudo] npm i -g hmh-cli

Os métodos são os mesmos da lib, que você pode passar por parâmetro, como --sum, --sub, --diff e --div.

Espaços em branco a mais ou a menos são ignorados, tanto na lib quanto na CLI. Mas, no caso dos métodos --diff e --div da CLI, que precisam ter 2 parâmetros, você pode fazer de duas formas:

1
$ hmh --diff 8h15m 11h30m

Juntando as horas e minutos, e separando os parâmetros por espaço. Ou ainda, usando aspas:

1
$ hmh --diff "8h 15m" "11h 30m"

O resultado é o mesmo =)

Para o método de divisão, mesmo esquema:

1
$ hmh --div 7h20m 4

ou

1
$ hmh --div "7h 20m" 4

E para ter a saída em minutos, use o parâmetro -o minutes ou --output minutes:

1
$ hmh --div "7h 20m" 4 -o minutes

O desenvolvimento

Nos próximos posts, vou abordar toda a etapa de desenvolvimento da lib, testes, integração com CI e a criação da CLI.

Fique ligado! :D

Gostou da ferramenta? Vai ser útil pra você? Já existe algo que faça isso? Comente! :D