@t0.labs/daxta 1.1.3 → 1.1.5

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,21 +1,17 @@
1
- <p align="center">
2
- <img src="https://cdn.jsdelivr.net/npm/@t0.labs/daxta@1.0.0/assets/logo.png" width="88" alt="DAxTA" />
3
- </p>
1
+ <picture>
2
+ <source media="(prefers-color-scheme: dark)" srcset="assets/logo-light.png">
3
+ <source media="(prefers-color-scheme: light)" srcset="assets/logo-dark.png">
4
+ <img alt="DAxTA" src="assets/logo-dark.png" width="120" height="120">
5
+ </picture>
4
6
 
5
- <h1 align="center">DAxTA</h1>
7
+ # DAxTA
6
8
 
7
- <p align="center"><strong>API Test → API Documentation</strong></p>
9
+ **API Test → API Documentation**
8
10
 
9
- <p align="center">
10
- You already wrote the tests.<br />
11
- Don't document the same thing twice.
12
- </p>
11
+ You already wrote the tests.
12
+ Don't document the same thing twice.
13
13
 
14
- <p align="center">
15
- <a href="https://www.npmjs.com/package/@t0.labs/daxta"><img alt="npm" src="https://img.shields.io/npm/v/@t0.labs/daxta?color=111111&label=npm&logo=npm" /></a>
16
- <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/@t0.labs/daxta?color=111111&label=node" /></a>
17
- <a href="LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@t0.labs/daxta?color=111111" /></a>
18
- </p>
14
+ ![npm](https://img.shields.io/npm/v/@t0.labs/daxta?color=111111&label=npm&logo=npm)![node](https://img.shields.io/node/v/@t0.labs/daxta?color=111111&label=node)![license](https://img.shields.io/npm/l/@t0.labs/daxta?color=111111)
19
15
 
20
16
  ---
21
17
 
@@ -30,13 +26,15 @@ DAxTA captures that real traffic while your tests run and turns it into interact
30
26
  ```ts
31
27
  import { apiDocs } from '@t0.labs/daxta';
32
28
 
33
- apiDocs(app); // NestJS — mount /docs when DAXTA_DOCS=on
29
+ apiDocs(app); // NestJS — mounts /docs on dev/test/staging NODE_ENV only
34
30
  ```
35
31
 
36
32
  Generation happens when Jest finishes (reporter) or when you run `daxta generate`. You do not call `generateApiDocs()` in `main.ts`.
37
33
 
38
34
  ---
39
35
 
36
+
37
+
40
38
  ## Why DAxTA?
41
39
 
42
40
  When you build an API, you already describe its behavior in your tests.
@@ -74,19 +72,23 @@ OpenAPI → Postman / other tools
74
72
 
75
73
  ---
76
74
 
75
+
76
+
77
77
  ## What you get
78
78
 
79
- | From your tests | In DAxTA |
80
- | --- | --- |
81
- | Real request / response pairs | Interactive `/api-docs` UI |
82
- | Positive scenarios | Success examples |
83
- | Negative scenarios | Error examples |
84
- | Validation failures | Invalid cases |
85
- | Authentication scenarios | Recorded headers |
86
- | Omitted / optional fields | DTO field metadata |
87
- | Status codes | Executable API calls |
88
- | Multiple test cases | Multiple examples per operation |
89
- | Recorded API set | OpenAPI + Postman export |
79
+
80
+ | From your tests | In DAxTA |
81
+ | ----------------------------- | ------------------------------- |
82
+ | Real request / response pairs | Interactive `/api-docs` UI |
83
+ | Positive scenarios | Success examples |
84
+ | Negative scenarios | Error examples |
85
+ | Validation failures | Invalid cases |
86
+ | Authentication scenarios | Recorded headers |
87
+ | Omitted / optional fields | DTO field metadata |
88
+ | Status codes | Executable API calls |
89
+ | Multiple test cases | Multiple examples per operation |
90
+ | Recorded API set | OpenAPI + Postman export |
91
+
90
92
 
91
93
  Different tests for the same endpoint automatically become different API examples.
92
94
 
@@ -104,6 +106,8 @@ These examples come from **actual test executions**, not manually maintained doc
104
106
 
105
107
  ---
106
108
 
109
+
110
+
107
111
  ## How it works
108
112
 
109
113
  ```text
@@ -130,19 +134,16 @@ These examples come from **actual test executions**, not manually maintained doc
130
134
  ```
131
135
 
132
136
  1. **Install** attaches DAxTA to Jest using `setupFilesAfterEnv` and a reporter.
133
-
134
- Your existing `test:integration` command remains the entrypoint. DAxTA does not wrap your test process.
135
-
137
+ Your existing `test:integration` command remains the entrypoint. DAxTA does not wrap your test process.
136
138
  2. **Run your tests normally.**
137
-
138
- DAxTA records the real HTTP traffic generated by your tests.
139
-
139
+ DAxTA records the real HTTP traffic generated by your tests.
140
140
  3. **When Jest finishes**, DAxTA performs a single documentation build.
141
-
142
- 4. `apiDocs(app)` mounts the generated documentation on your NestJS application when `DAXTA_DOCS=on`.
141
+ 4. `apiDocs(app)` mounts the generated documentation on your NestJS application in every environment except production.
143
142
 
144
143
  ---
145
144
 
145
+
146
+
146
147
  ## What DAxTA covers
147
148
 
148
149
  DAxTA records **real HTTP traffic** from NestJS API integration tests.
@@ -163,18 +164,22 @@ If Jest is wired (`setupFilesAfterEnv` + reporter), those hits become `/api-docs
163
164
 
164
165
  **Not covered** — anything that never passes through that HTTP client:
165
166
 
166
- | Test style | Recorded? |
167
- | --- | --- |
168
- | Nest e2e with `request(app.getHttpServer())` | Yes |
169
- | Service / unit tests (`TestingModule`, no HTTP) | No |
170
- | `axios`, `fetch`, `got` | No |
171
- | Playwright / Cypress | No |
172
- | GraphQL or WebSocket (unless over superagent HTTP) | No |
167
+
168
+ | Test style | Recorded? |
169
+ | -------------------------------------------------- | --------- |
170
+ | Nest e2e with `request(app.getHttpServer())` | Yes |
171
+ | Service / unit tests (`TestingModule`, no HTTP) | No |
172
+ | `axios`, `fetch`, `got` | No |
173
+ | Playwright / Cypress | No |
174
+ | GraphQL or WebSocket (unless over superagent HTTP) | No |
175
+
173
176
 
174
177
  If the test does not hit the API over HTTP the way your clients do, DAxTA has nothing to document. That is intentional: the source of truth is **observed API behavior**, not mocked internals.
175
178
 
176
179
  ---
177
180
 
181
+
182
+
178
183
  ## Install
179
184
 
180
185
  ```bash
@@ -197,10 +202,10 @@ pnpm run test:integration
197
202
 
198
203
  When Jest finishes, your documentation is ready.
199
204
 
200
- Start your application with DAxTA enabled:
205
+ Start your application as usual:
201
206
 
202
207
  ```bash
203
- DAXTA_DOCS=on pnpm start:dev
208
+ pnpm start:dev
204
209
  ```
205
210
 
206
211
  Open:
@@ -217,6 +222,40 @@ Flags: `--yes` · `--dry-run` · `--skip-main` · `--skip-dep` · `--main <path>
217
222
 
218
223
  ---
219
224
 
225
+
226
+
227
+ ## Uninstall
228
+
229
+ ```bash
230
+ pnpm dlx @t0.labs/daxta uninstall
231
+ ```
232
+
233
+ or, if DAxTA is already a dependency:
234
+
235
+ ```bash
236
+ pnpm daxta uninstall
237
+ ```
238
+
239
+ It unwinds everything the installer put in place: the `apiDocs(app)` call in your NestJS entrypoint, the Jest
240
+ reporter and setup hooks, the wrapped test script and any `daxta:*` scripts in `package.json`, `daxta.config.ts`,
241
+ the generated `daxta/` output directory, the `.gitignore` entries, and the legacy `DAXTA_DOCS` line if an older
242
+ install left one behind. `@t0.labs/daxta` itself is removed with your package manager unless you pass
243
+ `--keep-dep`.
244
+
245
+ Your tests are untouched — they were never DAxTA-specific to begin with.
246
+
247
+ Preview first if you want to see the plan without writing anything:
248
+
249
+ ```bash
250
+ pnpm dlx @t0.labs/daxta uninstall --dry-run
251
+ ```
252
+
253
+ Flags: `--yes` · `--dry-run` · `--keep-dep` · `--fast`
254
+
255
+ ---
256
+
257
+
258
+
220
259
  ## Docs UI
221
260
 
222
261
  DAxTA provides an interactive API workbench directly on your application.
@@ -245,6 +284,8 @@ Environment tokens only override keys that were actually recorded.
245
284
 
246
285
  ---
247
286
 
287
+
288
+
248
289
  ## DTO fields
249
290
 
250
291
  Field metadata is derived from `class-validator` / `class-transformer` DTO metadata together with observed traffic.
@@ -260,6 +301,8 @@ This allows DAxTA to understand required and optional fields without another doc
260
301
 
261
302
  ---
262
303
 
304
+
305
+
263
306
  ## OpenAPI export
264
307
 
265
308
  DAxTA is not limited to `/api-docs`.
@@ -288,25 +331,42 @@ Your tests remain the source of truth.
288
331
 
289
332
  ---
290
333
 
291
- ## `DAXTA_DOCS`
292
334
 
293
- DAxTA requires an explicit decision about whether `/docs` should be mounted. Only `on` and `off` are accepted.
294
335
 
295
- ```bash
296
- DAXTA_DOCS=on # mount /docs
297
- DAXTA_DOCS=off # do not mount /docs
336
+ ## When `/docs` is mounted
337
+
338
+ `apiDocs(app)` follows `NODE_ENV`, so the variable your application already sets decides it. There is no
339
+ DAxTA-specific flag to manage:
298
340
 
299
- # unset / empty / any other value → throws
341
+ ```bash
342
+ NODE_ENV=development pnpm start:dev # /docs mounted
343
+ NODE_ENV=dev # /docs mounted
344
+ NODE_ENV=test # /docs mounted
345
+ NODE_ENV=staging # /docs mounted
346
+ NODE_ENV=sta # /docs mounted
347
+ NODE_ENV=production # /docs not mounted
348
+ # NODE_ENV unset → /docs not mounted
300
349
  ```
301
350
 
302
- This makes exposing API documentation an explicit application decision.
351
+ The gate is closed by default: only `dev`, `development`, `test`, `sta` and `staging` open the docs. Anything
352
+ else — `production`, an unrecognised value, or no value at all — keeps them off, so a deployment that forgets to
353
+ set `NODE_ENV` never exposes them. `daxta install` adds `NODE_ENV=development` to your env file only when no env
354
+ file declares `NODE_ENV`; an existing value is yours and stays untouched.
355
+
356
+ Not mounting `/docs` does not remove `@t0.labs/daxta` from your Node image. It only skips the route.
303
357
 
304
- `DAXTA_DOCS=off` does not remove `@t0.labs/daxta` from your Node image. It only prevents `/docs` from being mounted.
358
+ The decision is exported if you need the same answer elsewhere:
359
+
360
+ ```ts
361
+ import { docsEnabled } from '@t0.labs/daxta';
362
+ ```
305
363
 
306
364
  The path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in `daxta.config.ts`.
307
365
 
308
366
  ---
309
367
 
368
+
369
+
310
370
  ## Commands
311
371
 
312
372
  ```bash
@@ -327,6 +387,8 @@ For most NestJS applications, `apiDocs(app)` is preferred over `daxta serve`.
327
387
 
328
388
  ---
329
389
 
390
+
391
+
330
392
  ## Sidebar order
331
393
 
332
394
  ```bash
@@ -358,6 +420,8 @@ daxta generate
358
420
 
359
421
  ---
360
422
 
423
+
424
+
361
425
  ## API
362
426
 
363
427
  **NestJS** — only this belongs in `main.ts`:
@@ -378,7 +442,7 @@ import { apiDocsHandler } from '@t0.labs/daxta';
378
442
  app.use(apiDocsHandler());
379
443
  ```
380
444
 
381
- `apiDocs(app)` works on Express too — it is `app.use(apiDocsHandler())` plus the `DAXTA_DOCS` gate.
445
+ `apiDocs(app)` works on Express too — it is `app.use(apiDocsHandler())` plus the `NODE_ENV` gate.
382
446
 
383
447
  **Standalone viewer** (CLI / rare):
384
448
 
@@ -390,6 +454,8 @@ serveApiDocs({ port: 5199 });
390
454
 
391
455
  ---
392
456
 
457
+
458
+
393
459
  ## The idea behind DAxTA
394
460
 
395
461
  The idea is simple.
@@ -410,14 +476,16 @@ It is just trapped inside your tests.
410
476
 
411
477
  **DAxTA turns it into something you can explore, execute, export, and share.**
412
478
 
413
- <p align="center"><strong>API Test → API Documentation</strong></p>
479
+ **API Test → API Documentation**
414
480
 
415
- <p align="center">You already wrote the tests. Let DAxTA write the docs.</p>
481
+ You already wrote the tests. Let DAxTA write the docs.
416
482
 
417
483
  ---
418
484
 
485
+
486
+
419
487
  ## License
420
488
 
421
489
  DAxTA is [MIT](LICENSE) licensed.
422
490
 
423
- Copyright (c) 2026 t0.labs
491
+ Copyright (c) 2026 t0.labs