Skip to content

Commit 43c927d

Browse files
pedromdevpedromdev
committed
docs: adiciona gráfico de fluxo de transformação
1 parent 5c3b558 commit 43c927d

File tree

3 files changed

+162
-93
lines changed

3 files changed

+162
-93
lines changed

‎docs/en/guide/how-it-works.md

Lines changed: 69 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,83 @@
1-
# Como Funciona
1+
# How it Works
22

3-
O TS to JSON Schema utiliza uma abordagem única para converter tipos TypeScript em JSON Schema. Em vez de gerar os schemas em tempo de compilação ou através de ferramentas CLI, a biblioteca funciona em tempo de execução, mantendo a tipagem forte do TypeScript.
3+
TS to JSON Schema uses a unique approach to convert TypeScript types to JSON Schema. Instead of generating schemas at compile time or through CLI tools, the library works at runtime while maintaining TypeScript's strong typing.
44

5-
## Arquitetura
5+
## Architecture
66

7-
A biblioteca é dividida em vários pacotes, cada um com uma responsabilidade específica:
7+
The library is divided into several packages, each with a specific responsibility:
88

99
### @ts-to-json-schema/core
1010

11-
O pacote core fornece a função principal `toJsonSchema` que você usa em seu código. Esta função parece simples na superfície, mas internamente ela:
11+
The core package provides the main `toJsonSchema` function that you use in your code. This function seems simple on the surface, but internally it:
1212

13-
1. Captura informações sobre o tipo TypeScript usado como parâmetro genérico
14-
2. Utiliza as informações coletadas pelo transformador para gerar o schema
15-
3. Aplica as configurações e personalizações definidas
13+
1. Captures information about the TypeScript type used as a generic parameter
14+
2. Uses the information collected by the transformer to generate the schema
15+
3. Applies the defined settings and customizations
1616

1717
### @ts-to-json-schema/transform
1818

19-
Este é o coração da mágica. O transformador:
19+
This is where the magic happens. The transformer:
2020

21-
1. É executado durante a compilação do TypeScript
22-
2. Analisa os tipos usando a API do Compilador TypeScript
23-
3. Coleta metadados sobre os tipos
24-
4. Injeta os metadados no código compilado
21+
1. Runs during TypeScript compilation
22+
2. Analyzes types using the TypeScript Compiler API
23+
3. Collects metadata about types
24+
4. Injects metadata into the compiled code
2525

2626
### @ts-to-json-schema/types
2727

28-
Contém as definições de tipos compartilhadas entre os pacotes, incluindo:
28+
Contains shared type definitions between packages, including:
2929

30-
- Tipos para configuração
31-
- Interfaces para os schemas
32-
- Tipos utilitários
30+
- Configuration types
31+
- Schema interfaces
32+
- Utility types
3333

3434
### @ts-to-json-schema/esbuild-plugin
3535

36-
Fornece integração com o ESBuild, permitindo:
36+
Provides ESBuild integration, allowing:
3737

38-
- Configuração automática do transformador
39-
- Otimização do processo de build
40-
- Suporte a várias configurações do ESBuild
38+
- Automatic transformer configuration
39+
- Build process optimization
40+
- Support for various ESBuild configurations
4141

42-
## Fluxo de Execução
42+
## Transformation Flow
4343

44-
1. **Tempo de Compilação**
45-
- O transformador analisa seu código TypeScript
46-
- Coleta informações sobre os tipos
47-
- Injeta os metadados no código compilado
44+
```mermaid
45+
graph TB
46+
subgraph "Compile Time"
47+
A[TypeScript Code] -->|@ts-to-json-schema/transform| B[Type Analysis]
48+
B -->|TS Compiler API| C[Metadata Collection]
49+
C --> D[Injection into JS Code]
50+
end
4851
49-
2. **Tempo de Execução**
50-
- Você chama `toJsonSchema<SeuTipo>()`
51-
- A função acessa os metadados injetados
52-
- Gera o JSON Schema correspondente
52+
subgraph "Runtime"
53+
E[toJsonSchema Call] -->|@ts-to-json-schema/core| F[Metadata Reading]
54+
F --> G[Schema Generation]
55+
G -->|@ts-to-json-schema/types| H[Final JSON Schema]
56+
end
5357
54-
## Exemplo Detalhado
58+
D -.->|Metadata Available| F
59+
60+
style A fill:#f9f,stroke:#333,stroke-width:2px
61+
style E fill:#bbf,stroke:#333,stroke-width:2px
62+
style H fill:#bfb,stroke:#333,stroke-width:2px
63+
```
64+
65+
## Execution Flow
66+
67+
1. **Compile Time**
68+
- The transformer analyzes your TypeScript code
69+
- Collects type information
70+
- Injects metadata into the compiled code
71+
72+
2. **Runtime**
73+
- You call `toJsonSchema<YourType>()`
74+
- The function accesses the injected metadata
75+
- Generates the corresponding JSON Schema
76+
77+
## Detailed Example
5578

5679
```typescript
57-
// 1. Defina seus tipos
80+
// 1. Define your types
5881
interface User {
5982
id: number;
6083
name: string;
@@ -65,10 +88,10 @@ interface User {
6588
};
6689
}
6790

68-
// 2. Use a função toJsonSchema
91+
// 2. Use the toJsonSchema function
6992
const schema = toJsonSchema<User>();
7093

71-
// 3. O schema gerado incluirá:
94+
// 3. The generated schema will include:
7295
// {
7396
// type: 'object',
7497
// properties: {
@@ -88,20 +111,20 @@ const schema = toJsonSchema<User>();
88111
// }
89112
```
90113

91-
## Vantagens desta Abordagem
114+
## Advantages of this Approach
92115

93-
1. **Sem Etapa Extra de Build**
94-
- Não precisa executar geradores
95-
- Integração natural com o fluxo de desenvolvimento
116+
1. **No Extra Build Step**
117+
- No need to run generators
118+
- Natural integration with development flow
96119

97-
2. **Tipagem Forte**
98-
- Mantém o TypeScript como fonte única da verdade
99-
- Erros de tipo são pegos em tempo de compilação
120+
2. **Strong Typing**
121+
- Keeps TypeScript as the single source of truth
122+
- Type errors are caught at compile time
100123

101124
3. **Performance**
102-
- Metadados são gerados apenas uma vez durante a compilação
103-
- Geração de schema é rápida em tempo de execução
125+
- Metadata is generated only once during compilation
126+
- Schema generation is fast at runtime
104127

105-
4. **Flexibilidade**
106-
- Suporte a tipos complexos
107-
- Personalizável através de configurações
128+
4. **Flexibility**
129+
- Support for complex types
130+
- Customizable through configurations

‎docs/es/guide/how-it-works.md

Lines changed: 70 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,83 @@
1-
# Como Funciona
1+
# Cómo Funciona
22

3-
O TS to JSON Schema utiliza uma abordagem única para converter tipos TypeScript em JSON Schema. Em vez de gerar os schemas em tempo de compilação ou através de ferramentas CLI, a biblioteca funciona em tempo de execução, mantendo a tipagem forte do TypeScript.
3+
TS to JSON Schema utiliza un enfoque único para convertir tipos TypeScript en JSON Schema. En lugar de generar schemas en tiempo de compilación o a través de herramientas CLI, la biblioteca funciona en tiempo de ejecución mientras mantiene el tipado fuerte de TypeScript.
44

5-
## Arquitetura
5+
## Arquitectura
66

7-
A biblioteca é dividida em vários pacotes, cada um com uma responsabilidade específica:
7+
La biblioteca está dividida en varios paquetes, cada uno con una responsabilidad específica:
88

99
### @ts-to-json-schema/core
1010

11-
O pacote core fornece a função principal `toJsonSchema` que você usa em seu código. Esta função parece simples na superfície, mas internamente ela:
11+
El paquete core proporciona la función principal `toJsonSchema` que usas en tu código. Esta función parece simple en la superficie, pero internamente:
1212

13-
1. Captura informações sobre o tipo TypeScript usado como parâmetro genérico
14-
2. Utiliza as informações coletadas pelo transformador para gerar o schema
15-
3. Aplica as configurações e personalizações definidas
13+
1. Captura información sobre el tipo TypeScript usado como parámetro genérico
14+
2. Utiliza la información recopilada por el transformador para generar el schema
15+
3. Aplica la configuración y personalizaciones definidas
1616

1717
### @ts-to-json-schema/transform
1818

19-
Este é o coração da mágica. O transformador:
19+
Aquí es donde ocurre la magia. El transformador:
2020

21-
1. É executado durante a compilação do TypeScript
22-
2. Analisa os tipos usando a API do Compilador TypeScript
23-
3. Coleta metadados sobre os tipos
24-
4. Injeta os metadados no código compilado
21+
1. Se ejecuta durante la compilación de TypeScript
22+
2. Analiza tipos usando la API del Compilador TypeScript
23+
3. Recopila metadatos sobre los tipos
24+
4. Inyecta metadatos en el código compilado
2525

2626
### @ts-to-json-schema/types
2727

28-
Contém as definições de tipos compartilhadas entre os pacotes, incluindo:
28+
Contiene definiciones de tipos compartidas entre paquetes, incluyendo:
2929

30-
- Tipos para configuração
31-
- Interfaces para os schemas
32-
- Tipos utilitários
30+
- Tipos de configuración
31+
- Interfaces de schema
32+
- Tipos utilitarios
3333

3434
### @ts-to-json-schema/esbuild-plugin
3535

36-
Fornece integração com o ESBuild, permitindo:
36+
Proporciona integración con ESBuild, permitiendo:
3737

38-
- Configuração automática do transformador
39-
- Otimização do processo de build
40-
- Suporte a várias configurações do ESBuild
38+
- Configuración automática del transformador
39+
- Optimización del proceso de build
40+
- Soporte para varias configuraciones de ESBuild
4141

42-
## Fluxo de Execução
42+
## Flujo de Transformación
4343

44-
1. **Tempo de Compilação**
45-
- O transformador analisa seu código TypeScript
46-
- Coleta informações sobre os tipos
47-
- Injeta os metadados no código compilado
44+
```mermaid
45+
graph TB
46+
subgraph "Tiempo de Compilación"
47+
A[Código TypeScript] -->|@ts-to-json-schema/transform| B[Análisis de Tipos]
48+
B -->|API del Compilador TS| C[Recopilación de Metadatos]
49+
C --> D[Inyección en Código JS]
50+
end
4851
49-
2. **Tempo de Execução**
50-
- Você chama `toJsonSchema<SeuTipo>()`
51-
- A função acessa os metadados injetados
52-
- Gera o JSON Schema correspondente
52+
subgraph "Tiempo de Ejecución"
53+
E[Llamada toJsonSchema] -->|@ts-to-json-schema/core| F[Lectura de Metadatos]
54+
F --> G[Generación del Schema]
55+
G -->|@ts-to-json-schema/types| H[JSON Schema Final]
56+
end
5357
54-
## Exemplo Detalhado
58+
D -.->|Metadatos Disponibles| F
59+
60+
style A fill:#f9f,stroke:#333,stroke-width:2px
61+
style E fill:#bbf,stroke:#333,stroke-width:2px
62+
style H fill:#bfb,stroke:#333,stroke-width:2px
63+
```
64+
65+
## Flujo de Ejecución
66+
67+
1. **Tiempo de Compilación**
68+
- El transformador analiza tu código TypeScript
69+
- Recopila información sobre los tipos
70+
- Inyecta metadatos en el código compilado
71+
72+
2. **Tiempo de Ejecución**
73+
- Llamas a `toJsonSchema<TuTipo>()`
74+
- La función accede a los metadatos inyectados
75+
- Genera el JSON Schema correspondiente
76+
77+
## Ejemplo Detallado
5578

5679
```typescript
57-
// 1. Defina seus tipos
80+
// 1. Define tus tipos
5881
interface User {
5982
id: number;
6083
name: string;
@@ -65,10 +88,10 @@ interface User {
6588
};
6689
}
6790

68-
// 2. Use a função toJsonSchema
91+
// 2. Usa la función toJsonSchema
6992
const schema = toJsonSchema<User>();
7093

71-
// 3. O schema gerado incluirá:
94+
// 3. El schema generado incluirá:
7295
// {
7396
// type: 'object',
7497
// properties: {
@@ -88,20 +111,20 @@ const schema = toJsonSchema<User>();
88111
// }
89112
```
90113

91-
## Vantagens desta Abordagem
114+
## Ventajas de este Enfoque
92115

93-
1. **Sem Etapa Extra de Build**
94-
- Não precisa executar geradores
95-
- Integração natural com o fluxo de desenvolvimento
116+
1. **Sin Paso Extra de Build**
117+
- No necesitas ejecutar generadores
118+
- Integración natural con el flujo de desarrollo
96119

97-
2. **Tipagem Forte**
98-
- Mantém o TypeScript como fonte única da verdade
99-
- Erros de tipo são pegos em tempo de compilação
120+
2. **Tipado Fuerte**
121+
- Mantiene TypeScript como única fuente de verdad
122+
- Los errores de tipo se detectan en tiempo de compilación
100123

101-
3. **Performance**
102-
- Metadados são gerados apenas uma vez durante a compilação
103-
- Geração de schema é rápida em tempo de execução
124+
3. **Rendimiento**
125+
- Los metadatos se generan solo una vez durante la compilación
126+
- La generación de schema es rápida en tiempo de ejecución
104127

105-
4. **Flexibilidade**
106-
- Suporte a tipos complexos
107-
- Personalizável através de configurações
128+
4. **Flexibilidad**
129+
- Soporte para tipos complejos
130+
- Personalizable a través de configuraciones

‎docs/pt-BR/guide/how-it-works.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,29 @@ Fornece integração com o ESBuild, permitindo:
3939
- Otimização do processo de build
4040
- Suporte a várias configurações do ESBuild
4141

42+
## Fluxo de Transformação
43+
44+
```mermaid
45+
graph TB
46+
subgraph "Tempo de Compilação"
47+
A[Código TypeScript] -->|@ts-to-json-schema/transform| B[Análise de Tipos]
48+
B -->|API do Compilador TS| C[Coleta de Metadados]
49+
C --> D[Injeção no Código JS]
50+
end
51+
52+
subgraph "Tempo de Execução"
53+
E[Chamada toJsonSchema] -->|@ts-to-json-schema/core| F[Leitura de Metadados]
54+
F --> G[Geração do Schema]
55+
G -->|@ts-to-json-schema/types| H[JSON Schema Final]
56+
end
57+
58+
D -.->|Metadados Disponíveis| F
59+
60+
style A fill:#f9f,stroke:#333,stroke-width:2px
61+
style E fill:#bbf,stroke:#333,stroke-width:2px
62+
style H fill:#bfb,stroke:#333,stroke-width:2px
63+
```
64+
4265
## Fluxo de Execução
4366

4467
1. **Tempo de Compilação**

0 commit comments

Comments
 (0)