@t0.labs/daxta 0.3.7 → 0.4.1

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
@@ -1,8 +1,45 @@
1
- # @t0.labs/daxta
1
+ # DAxTA
2
2
 
3
- DAxTA — NestJS integration-test traffic → API docs, DTO required/optional, terminal Try-it, and app `/docs`.
3
+ **Document API × Test API** — NestJS integration tests already hit your real endpoints. DAxTA records that traffic and turns it into living OpenAPI docs on your app port (`/docs`), with DTO required/optional fields and a Try-it workbench.
4
4
 
5
- ## Install (one command)
5
+ Swagger asks you to decorate controllers. DAxTA learns from what your tests actually call.
6
+
7
+ DAxTA docs — recorded request, response, Try-it
8
+
9
+ ## What you get
10
+
11
+
12
+ | After tests | On the app |
13
+ | ------------------------------------- | -------------------------------------------------------- |
14
+ | OpenAPI + HTML from real hits | `/docs` on the same port as Nest |
15
+ | Success / validation / auth scenarios | Send + Copy cURL from recorded calls |
16
+ | DTO field map (required vs optional) | `DAXTA_DOCS=true|false` gate (like Swagger’s prod check) |
17
+
18
+
19
+ Jest finishes — Docs ready on /docs
20
+
21
+ ## How it works
22
+
23
+ ```text
24
+ your Jest suite
25
+ │ supertest / superagent hits
26
+ ▼
27
+ DAxTA records hits to disk
28
+ │ (no OpenAPI rebuild mid-run)
29
+ ▼
30
+ onRunComplete → one full build
31
+ │
32
+ ▼
33
+ Docs ready → http://localhost:3000/docs
34
+ ```
35
+
36
+ 1. **Install** attaches DAxTA as a Jest plugin (`setupFilesAfterEnv` + reporter). Your existing `test:integration` stays the entrypoint — DAxTA does not wrap the process.
37
+ 2. **During the run** only traffic is recorded (disk flush). OpenAPI/HTML is built once when Jest finishes.
38
+ 3. `apiDocs(app)` in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
39
+
40
+
41
+
42
+ ## Install
6
43
 
7
44
  ```bash
8
45
  pnpm dlx @t0.labs/daxta install
@@ -10,35 +47,63 @@ pnpm dlx @t0.labs/daxta install
10
47
  npx @t0.labs/daxta install
11
48
  ```
12
49
 
13
- Install attaches DAxTA as a **Jest plugin** (setup + reporter) on your existing jest config.
14
- Your `test:integration` (or whatever you pick) stays the entrypoint — DAxTA does **not** wrap the process.
50
+ Wires `apiDocs(app)` into your Nest entry and hooks Jest. Then:
15
51
 
16
52
  ```ts
17
53
  import { apiDocs } from '@t0.labs/daxta';
18
- apiDocs(app); // needs DAXTA_DOCS
54
+
55
+ apiDocs(app); // requires DAXTA_DOCS in the environment
19
56
  ```
20
57
 
21
- ## Required env
58
+ ```bash
59
+ pnpm run test:integration # Docs ready when Jest finishes
60
+ DAXTA_DOCS=true pnpm start:dev # open /docs on the app port
61
+ ```
62
+
63
+
64
+
65
+ ## Docs UI
66
+
67
+ Recorded scenarios (success, validation, missing auth) stay tied to the request that produced them — headers included. Empty auth on a 401 scenario stays empty; env tokens only override keys that were actually recorded.
68
+
69
+ Scenario picker — success, validation, auth
70
+
71
+ Field metadata comes from class-validator / class-transformer DTOs plus observed traffic:
72
+
73
+ Required vs optional DTO fields
74
+
75
+ ## `DAXTA_DOCS` (required)
76
+
77
+ Same idea as Nest Swagger’s “don’t call `setup` in prod”:
22
78
 
23
79
  ```bash
24
- DAXTA_DOCS=true # enable /docs on the app port
25
- DAXTA_DOCS=false # disable (must be set)
80
+ DAXTA_DOCS=true # mount /docs
81
+ DAXTA_DOCS=false # no-op (must still be set)
82
+ # unset / empty → throws — make the choice explicit
26
83
  ```
27
84
 
28
- ## Usage
85
+ `false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting `/docs`.
86
+
87
+ ## Commands
29
88
 
30
89
  ```bash
31
- pnpm run test:integration # your script — Docs ready prints when Jest finishes
32
- daxta migrate # force upgrade after package bump
33
- daxta serve # standalone viewer (optional)
90
+ daxta install # one-shot setup
91
+ daxta migrate # after a package bump
92
+ daxta build # rebuild OpenAPI/HTML from recorded hits
93
+ daxta serve # optional standalone viewer (prefer apiDocs on the app)
94
+ daxta fields … # export field map for an operation
95
+ daxta call … # CLI Try-it
34
96
  ```
35
97
 
98
+
99
+
36
100
  ## API
37
101
 
38
102
  ```ts
39
103
  import { apiDocs, apiDocsHandler, serveApiDocs } from '@t0.labs/daxta';
40
104
 
41
- apiDocs(app);
42
- app.use(apiDocsHandler());
43
- serveApiDocs({ port: 5199 });
105
+ apiDocs(app); // preferred — same origin as the API
106
+ app.use(apiDocsHandler()); // Express-style mount
107
+ serveApiDocs({ port: 5199 }); // standalone (CLI / rare)
44
108
  ```
109
+