TypeScript
A utilização de uma linguagem tipificada é fortemente recomendada.
Para utilizadores de Typescript, fornecemos vários pacotes no npm com a tipificação de todos os conceitos utilizados nos módulos do GO (ex: APEX, GTFS, APIs públicos, etc.)
Estes pacotes são atualizados frequentemente e utilizam Calendar Versioning. Temos consciência que é mais complexo garantir a estabilidade de versões, e distinguir entre patch, minor e major updates, mas é um trade-off que consideramos aceitável, fundamental para manter a rapidez no desenvolvimento do GO.
Recomendamos instalar apenas os pacotes necessários para consumir os dados do API público:
| Nome do pacote | Descrição |
|---|---|
@tmlmobilidade/go-types-shared | Tipos comuns a todos os módulos do GO, com conceitos fundamentais como datas, números, estados, entre outros. Quase todos os outros pacotes, senão todos, têm este como dependência. |
@tmlmobilidade/go-types-hub | Tipos específicos para o módulo Hub de dados abertos. Contém as estruturas do ficheiro GTFS unificado assim como as respostas do API. |
@tmlmobilidade/go-types-gtfs | Implementação em Typescript dos tipos do standard GTFS como especificado na documentação oficial em gtfs.org |
@tmlmobilidade/go-types-gtfs-rt | Implementação em Typescript dos tipos do standard GTFS-RT como especificado na documentação oficial em gtfs.org |
@tmlmobilidade/go-utils-dates | Conjunto de funções para trabalhar com datas. Facilita a geração de conceitos como datas operacionais (24h+), conversão de fusos horários, entre outros. É recomendado utilizar em conjunto com os dados do API pois facilita a transformação minimizando erros de compilação. |
Temos mais pacotes, incluindo utilitários para importar GTFS, descodificar Protbuf, entre outros, mas consideramos que são mais específicos à utilização do GO em si, pelo que não recomendamos a sua utilização sob o risco de alterações inesperadas ao seu funcionamento entre versões.
Tipos Comuns
Existem tipos comuns a todos os módulos do GO, que representam conceitos operacionais como datas, estados, números, entre outros. Fica aqui uma lista não exaustiva dos principais:
| Branded Type | Native Type | Descrição |
|---|---|---|
OperationalDate | Number | Dia operacional, que normalmente vai entre as 04h e as 03h59 do dia seguinte. O conceito de data operacional é fundamental para se compreender as redes de transporte público. Representa a data a que o serviço de transporte está afeto, e não a data de calendário. Uma viagem que começa às 23h45 com uma duração de 1h30 irá terminar às 01h15 do dia seguinte. Por isso, os horários de passagem nessas paragens aparecem associados ao dia de calendário anterior. |
OperationalTime | String | A hora operacional é um conceito do GTFS utilizado para representar horas para lá das 24h. Por exemplo, uma viagem que começa às 22h00 no dia 21 de Janeiro e tem uma duração de 8h (comboio noturno) irá chegar ao seu destino às 30h00 do dia operacional 20260121, que representam as 06h da manhã do dia 22 de Janeiro em dias de calendário. |
UnixMilliseconds | Number | Número de millisegundos desde 1 Janeiro de 1970, às 00h00. Representa um selo temporal independente do fuso horário do utilizador ou do servidor. |
UnixSeconds | Number | Número de segundos desde 1 Janeiro de 1970, às 00h00. Representa um selo temporal independente do fuso horário do utilizador ou do servidor. |
TimezoneIdentified | String | Etiqueta de fuso horário de acordo com a base de dados da IANA. |
LanguageTag | String | Etiqueta de idioma de acordo com a base de dados da IANA. |
HexColor | String | Cor em formato hexadecimal, com o prefixo #. |