typoa 1.0.0-alpha.7 → 1.0.0-alpha.71

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,16 +3,15 @@
3
3
  <h1>typoa</h1>
4
4
  <h2> <b>Typ</b>escript <b>O</b>pen<b>A</b>PI Generator</h2>
5
5
 
6
- This tools is inspired from [tsoa](https://github.com/lukeautry/tsoa), the purpose is to be able to generate openapi definitions and express routes definitions via Typescript typings.
6
+ This tools is inspired from [tsoa](https://github.com/lukeautry/tsoa), the purpose is to be able to generate openapi definitions and express routes definitions via Typescript typings.
7
7
 
8
- We're using [ts-morph](https://github.com/dsherret/ts-morph) under the hood.
8
+ We're using [ts-morph](https://github.com/dsherret/ts-morph) under the hood.
9
9
 
10
- [![codecov](https://codecov.io/gh/Eywek/typoa/branch/main/graph/badge.svg?token=8hLCf5qoDU)](https://codecov.io/gh/Eywek/typoa)
11
10
  </div>
12
11
 
13
12
  ## Why
14
13
 
15
- Tsoa is a great package and it's working fine for simple typescript typings, which I think are the principal use case, It's used by many developers and It's maintained.
14
+ Tsoa is a great package and it's working fine for simple typescript typings, which I think are principal use cases, it's used by many developers and maintained.
16
15
 
17
16
  **BUT**, I've used tsoa in production projects and I've encountered many issues (I was able to [fix](https://github.com/lukeautry/tsoa/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Amerged+author%3AEywek) some of them), but when I've tried to use more complex types (inheritance, deep generics, conditionnal types...) tsoa wasn't able to provide me good openapi definitions, and without even telling me it failed to generate the right schema.
18
17
 
@@ -37,12 +36,12 @@ You only need to add the `@Route()` decorator at the top of your controller clas
37
36
  of each method definition, like this:
38
37
 
39
38
  ```ts
40
- import { Route, Get } from 'typoa'
39
+ import { Route, Get } from 'typoa/runtime'
41
40
 
42
41
  @Route()
43
42
  class MyController {
44
43
  @Get()
45
- public get () {}
44
+ public get() {}
46
45
  }
47
46
  ```
48
47
 
@@ -51,12 +50,12 @@ You can provide the route path in the `@Route()` decorator or in each verb decor
51
50
  You also will need to extends the `Controller` class if you want to override the default HTTP status (200 if your method return content, 204 if not):
52
51
 
53
52
  ```ts
54
- import { Route, Get, Controller } from 'typoa'
53
+ import { Route, Get, Controller } from 'typoa/runtime'
55
54
 
56
55
  @Route('/controller-path')
57
56
  class MyController extends Controller {
58
57
  @Get('/method-path')
59
- public get () {
58
+ public get() {
60
59
  this.setStatus(201)
61
60
  return 'Created'
62
61
  }
@@ -71,14 +70,12 @@ If you return a stream, `typoa` will stream it to the client.
71
70
  To use the parsed (and validated) body from typoa you only need to provide the `@Body()` decorator:
72
71
 
73
72
  ```ts
74
- import { Route, Get, Controller } from 'typoa'
73
+ import { Route, Get, Controller } from 'typoa/runtime'
75
74
 
76
75
  @Route('/controller-path')
77
76
  class MyController extends Controller {
78
77
  @Post('/method-path')
79
- public post (
80
- @Body() body: { name: string }
81
- ) {
78
+ public post(@Body() body: { name: string }) {
82
79
  this.setStatus(201)
83
80
  return 'Created'
84
81
  }
@@ -98,22 +95,29 @@ Sometimes you want to validate the body against a specific schema depending on w
98
95
  To handle that, you can provide a `discriminator function` to the body decorator:
99
96
 
100
97
  ```ts
101
- import { Route, Get, Controller, BodyDiscriminatorFunction } from 'typoa'
98
+ import {
99
+ Route,
100
+ Get,
101
+ Controller,
102
+ BodyDiscriminatorFunction
103
+ } from 'typoa/runtime'
102
104
 
103
105
  type TypeA = { name: string }
104
106
  type TypeB = { name: number }
105
107
 
106
108
  // The function need to return the name of the type you want to validate against
107
- export const discriminatorFunction: BodyDiscriminatorFunction = async (req) => 'TypeA'
109
+ export const discriminatorFunction: BodyDiscriminatorFunction = async req =>
110
+ 'TypeA'
108
111
 
109
112
  @Route('/controller-path')
110
113
  class MyController extends Controller {
111
114
  @Post('/method-path')
112
- public post (
115
+ public post(
113
116
  @Body(
114
117
  'application/json', // body content-type
115
118
  discriminatorFunction // name of the function you want to use
116
- ) body: TypeA | TypeB
119
+ )
120
+ body: TypeA | TypeB
117
121
  ) {
118
122
  this.setStatus(201)
119
123
  return 'Created'
@@ -126,23 +130,30 @@ class MyController extends Controller {
126
130
  To generate the openapi definition and the router you will need to bind to express, you only need to call the `generate` method of `typoa`:
127
131
 
128
132
  ```ts
133
+ import { generate } from 'typoa'
134
+
129
135
  await generate({
130
136
  tsconfigFilePath: path.resolve(__dirname, './tsconfig.json'),
131
137
  controllers: [path.resolve(__dirname, './*.ts')], // Path of your controllers
132
138
  openapi: {
133
- filePath: '/tmp/openapi.json', // Where do you want to generate your openapi file
134
- format: 'json', // 'json' | 'yaml'
135
- service: { // Used in the openapi definitions
139
+ // Where do you want to generate your openapi file (or array of file paths)
140
+ // The file extension (.json, .yaml, or .yml) determines the output format
141
+ filePath: '/tmp/openapi.json',
142
+ service: {
143
+ // Used in the openapi definitions
136
144
  name: 'my-service',
137
145
  version: '1.0.0'
138
146
  },
139
- securitySchemes: { // Openapi securitySchemes definitions
147
+ securitySchemes: {
148
+ // Openapi securitySchemes definitions
140
149
  company: {
141
150
  type: 'apiKey',
142
151
  name: 'x-company-id',
143
152
  in: 'header'
144
153
  }
145
- }
154
+ },
155
+ // Optional, fail on a misspelled JSDoc tag (e.g. @minLenght) instead of a logger warning
156
+ strictJsDocTags: true
146
157
  },
147
158
  router: {
148
159
  filePath: './router.ts', // Where do you want to generate the router file
@@ -150,3 +161,15 @@ await generate({
150
161
  }
151
162
  })
152
163
  ```
164
+
165
+ ### Runtime imports
166
+
167
+ `typoa` is the generator entry point and loads `ts-morph` (the TypeScript compiler), which costs tens of MiB of memory.
168
+ Code that runs in your service (controllers, decorators, `Controller`, `setRuntimeOptions`...) should import from `typoa/runtime` instead, which never loads it:
169
+
170
+ ```ts
171
+ import { Route, Get, Controller, setRuntimeOptions } from 'typoa/runtime'
172
+ ```
173
+
174
+ Keep `import { generate } from 'typoa'` in your generation script only.
175
+ The generated router imports from `typoa/runtime` by default (override with `router.runtimeImport`).
@@ -1,4 +1,5 @@
1
1
  import { OpenAPIV3 } from 'openapi-types';
2
2
  import { ClassDeclaration } from 'ts-morph';
3
3
  import { CodeGenControllers } from './types';
4
- export declare function addController(controller: ClassDeclaration, spec: OpenAPIV3.Document, codegenControllers: CodeGenControllers): void;
4
+ import { OpenAPIConfiguration } from './';
5
+ export declare function addController(controller: ClassDeclaration, spec: OpenAPIV3.Document, codegenControllers: CodeGenControllers, config: OpenAPIConfiguration['router']): void;