@t0.labs/daxta 1.1.1 → 1.1.2

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
@@ -30,7 +30,7 @@ DAxTA captures that real traffic while your tests run and turns it into interact
30
30
  ```ts
31
31
  import { apiDocs } from '@t0.labs/daxta';
32
32
 
33
- apiDocs(app); // NestJS — mount /api-docs when DAXTA_DOCS=true
33
+ apiDocs(app); // NestJS — mount /docs when DAXTA_DOCS=on
34
34
  ```
35
35
 
36
36
  Generation happens when Jest finishes (reporter) or when you run `daxta generate`. You do not call `generateApiDocs()` in `main.ts`.
@@ -139,7 +139,7 @@ These examples come from **actual test executions**, not manually maintained doc
139
139
 
140
140
  3. **When Jest finishes**, DAxTA performs a single documentation build.
141
141
 
142
- 4. `apiDocs(app)` mounts the generated documentation on your NestJS application when `DAXTA_DOCS=true`.
142
+ 4. `apiDocs(app)` mounts the generated documentation on your NestJS application when `DAXTA_DOCS=on`.
143
143
 
144
144
  ---
145
145
 
@@ -200,7 +200,7 @@ When Jest finishes, your documentation is ready.
200
200
  Start your application with DAxTA enabled:
201
201
 
202
202
  ```bash
203
- DAXTA_DOCS=true pnpm start:dev
203
+ DAXTA_DOCS=on pnpm start:dev
204
204
  ```
205
205
 
206
206
  Open:
@@ -290,20 +290,20 @@ Your tests remain the source of truth.
290
290
 
291
291
  ## `DAXTA_DOCS`
292
292
 
293
- DAxTA requires an explicit decision about whether `/api-docs` should be mounted.
293
+ DAxTA requires an explicit decision about whether `/docs` should be mounted. Only `on` and `off` are accepted.
294
294
 
295
295
  ```bash
296
- DAXTA_DOCS=true # mount /api-docs
297
- DAXTA_DOCS=false # do not mount /api-docs
296
+ DAXTA_DOCS=on # mount /docs
297
+ DAXTA_DOCS=off # do not mount /docs
298
298
 
299
- # unset / empty → throws
299
+ # unset / empty / any other value → throws
300
300
  ```
301
301
 
302
302
  This makes exposing API documentation an explicit application decision.
303
303
 
304
- `DAXTA_DOCS=false` does not remove `@t0.labs/daxta` from your Node image. It only prevents `/api-docs` from being mounted.
304
+ `DAXTA_DOCS=off` does not remove `@t0.labs/daxta` from your Node image. It only prevents `/docs` from being mounted.
305
305
 
306
- The path is configurable via `docsPath` in `daxta.config.ts` (default `/api-docs`).
306
+ The path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in `daxta.config.ts`.
307
307
 
308
308
  ---
309
309
 
package/assets/empty.html CHANGED
@@ -139,7 +139,7 @@
139
139
  </head>
140
140
  <body>
141
141
  <header class="topnav">
142
- <span class="nav-meta">/api-docs</span>
142
+ <span class="nav-meta">/docs</span>
143
143
  </header>
144
144
  <main class="stage">
145
145
  <div class="panel">
@@ -1543,7 +1543,7 @@
1543
1543
  const viewer = spec["x-viewer"] || {};
1544
1544
  const workspace = (spec.info && spec.info["x-workspace"]) || viewer.workspace || "";
1545
1545
  const defaultBaseUrlFromSpec = String((viewer.baseUrl || (spec.servers && spec.servers[0] && spec.servers[0].url) || "http://localhost:3000")).replace(/\/$/, "");
1546
- const docsPathSuffix = String(viewer.docsPath || "/api-docs").replace(/\/$/, "") || "/api-docs";
1546
+ const docsPathSuffix = String(viewer.docsPath || "/docs").replace(/\/$/, "") || "/docs";
1547
1547
 
1548
1548
  const inferBaseUrlFromLocation = () => {
1549
1549
  if (typeof location === "undefined") return null;
@@ -1336,7 +1336,7 @@
1336
1336
  const viewer = spec["x-viewer"] || {};
1337
1337
  const workspace = (spec.info && spec.info["x-workspace"]) || viewer.workspace || "";
1338
1338
  const defaultBaseUrlFromSpec = String((viewer.baseUrl || (spec.servers && spec.servers[0] && spec.servers[0].url) || "http://localhost:3000")).replace(/\/$/, "");
1339
- const docsPathSuffix = String(viewer.docsPath || "/api-docs").replace(/\/$/, "") || "/api-docs";
1339
+ const docsPathSuffix = String(viewer.docsPath || "/docs").replace(/\/$/, "") || "/docs";
1340
1340
 
1341
1341
  const inferBaseUrlFromLocation = () => {
1342
1342
  if (typeof location === "undefined") return null;
@@ -118,7 +118,7 @@ export default defineConfig({
118
118
  baseUrl: 'http://localhost:3000',
119
119
  controllersRoot: 'src',
120
120
  outDir: '.daxta/out',
121
- docsPath: '/api-docs',
121
+ docsPath: '/docs',
122
122
  treeLayout: 'role-resource',
123
123
  treeSkipParams: true,
124
124
  exampleLabelStyle: 'status-title-case',
@@ -158,7 +158,7 @@ function ensureGitignore(cwd, dryRun) {
158
158
  return added.map((e) => `.gitignore += ${e}`);
159
159
  }
160
160
  const ENV_CANDIDATES = ['.env', '.env.local', '.env.development', '.env.development.local'];
161
- /** Ensure DAXTA_DOCS is present (default true). Mirrors uninstall strip. */
161
+ /** Ensure DAXTA_DOCS is present (default on). Mirrors uninstall strip. */
162
162
  function ensureEnvDaxtaDocs(cwd, dryRun) {
163
163
  for (const name of ENV_CANDIDATES) {
164
164
  const filePath = path.join(cwd, name);
@@ -171,7 +171,7 @@ function ensureEnvDaxtaDocs(cwd, dryRun) {
171
171
  const targetName = ENV_CANDIDATES.find((name) => (0, fs_1.existsSync)(path.join(cwd, name))) ?? '.env';
172
172
  const targetPath = path.join(cwd, targetName);
173
173
  const created = !(0, fs_1.existsSync)(targetPath);
174
- const line = 'DAXTA_DOCS=true';
174
+ const line = 'DAXTA_DOCS=on';
175
175
  if (!dryRun) {
176
176
  if (created) {
177
177
  (0, fs_1.writeFileSync)(targetPath, `${line}\n`);
@@ -182,7 +182,7 @@ function ensureEnvDaxtaDocs(cwd, dryRun) {
182
182
  (0, fs_1.writeFileSync)(targetPath, next);
183
183
  }
184
184
  }
185
- return created ? `created ${targetName} (+ DAXTA_DOCS=true)` : `${targetName} += DAXTA_DOCS=true`;
185
+ return created ? `created ${targetName} (+ DAXTA_DOCS=on)` : `${targetName} += DAXTA_DOCS=on`;
186
186
  }
187
187
  function runPackageInstall(cwd, pm, version, dryRun) {
188
188
  if (dryRun)
@@ -344,7 +344,7 @@ async function installDaxta(options = {}) {
344
344
  }
345
345
  (0, ui_1.box)('Ready', [
346
346
  `${ui_1.c.mint('✔')} ${ui_1.c.bold(project)} · DAxTA ${ui_1.c.gold(`v${version}`)}`,
347
- `${ui_1.c.dim('api docs')} ${ui_1.c.ice('/api-docs')} · ${ui_1.c.ice('DAXTA_DOCS=true')}`,
347
+ `${ui_1.c.dim('api docs')} ${ui_1.c.ice('/docs')} · ${ui_1.c.ice('DAXTA_DOCS=on')}`,
348
348
  `${ui_1.c.dim('tests')} same script — titles first, spec after`,
349
349
  `${ui_1.c.dim('retune')} ${ui_1.c.ice('daxta tree')} · ${ui_1.c.ice('daxta titles')}`,
350
350
  ]);
@@ -356,7 +356,7 @@ async function installDaxta(options = {}) {
356
356
  },
357
357
  {
358
358
  cmd: `${pm} start:dev`,
359
- why: 'open /api-docs (DAXTA_DOCS already in .env)',
359
+ why: 'open /docs (DAXTA_DOCS=on already in .env)',
360
360
  },
361
361
  ]);
362
362
  }
package/dist/config.d.ts CHANGED
@@ -47,6 +47,10 @@ export type DaxtaConfig = {
47
47
  exampleLabelStyle?: ExampleLabelStyle;
48
48
  port?: number;
49
49
  fieldsFile?: string;
50
+ /**
51
+ * URL prefix for the viewer. Default `/docs`.
52
+ * Override with env `DAXTA_DOCS_PATH` (e.g. `/docs` or `docs`).
53
+ */
50
54
  docsPath?: string;
51
55
  /**
52
56
  * Persisted Try-it env/header store (survives rebuild). Default `.daxta/viewer-store.json`.
@@ -67,6 +71,8 @@ export type DaxtaConfig = {
67
71
  treePathSegments?: (pathTemplate: string) => string[] | undefined;
68
72
  };
69
73
  export type ResolvedDaxtaConfig = Required<Pick<DaxtaConfig, 'workspace' | 'baseUrl' | 'controllersRoot' | 'outDir' | 'treeLayout' | 'treePathOverrides' | 'treeSkipParams' | 'exampleLabelStyle' | 'port' | 'fieldsFile' | 'docsPath' | 'viewerStoreFile'>> & DaxtaConfig;
74
+ export declare const DEFAULT_DOCS_PATH = "/docs";
75
+ export declare function normalizeDocsPath(raw?: string | null): string;
70
76
  export declare function defineConfig(config: DaxtaConfig): DaxtaConfig;
71
77
  export declare function normalizeTreeLayout(layout: TreeLayout | LegacyTreeLayout | undefined): TreeLayout;
72
78
  export declare function resolveConfig(cwd?: string, overrides?: DaxtaConfig): ResolvedDaxtaConfig;
package/dist/config.js CHANGED
@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.DEFAULT_DOCS_PATH = void 0;
37
+ exports.normalizeDocsPath = normalizeDocsPath;
36
38
  exports.defineConfig = defineConfig;
37
39
  exports.normalizeTreeLayout = normalizeTreeLayout;
38
40
  exports.resolveConfig = resolveConfig;
@@ -52,13 +54,19 @@ const DEFAULTS = {
52
54
  exampleLabelStyle: 'status-title-case',
53
55
  port: 5199,
54
56
  fieldsFile: '.daxta/out/fields.json',
55
- docsPath: '/api-docs',
57
+ docsPath: '/docs',
56
58
  viewerStoreFile: '.daxta/viewer-store.json',
57
59
  envPresets: {
58
60
  local: { baseUrl: 'http://localhost:3000' },
59
61
  },
60
62
  };
61
63
  let cached = null;
64
+ exports.DEFAULT_DOCS_PATH = '/docs';
65
+ function normalizeDocsPath(raw) {
66
+ const value = String(raw ?? exports.DEFAULT_DOCS_PATH).trim() || exports.DEFAULT_DOCS_PATH;
67
+ const withSlash = value.startsWith('/') ? value : `/${value}`;
68
+ return withSlash.replace(/\/$/, '') || exports.DEFAULT_DOCS_PATH;
69
+ }
62
70
  function defineConfig(config) {
63
71
  return config;
64
72
  }
@@ -106,6 +114,7 @@ function resolveConfig(cwd = process.cwd(), overrides) {
106
114
  if (merged.exampleLabelStyle == null)
107
115
  merged.exampleLabelStyle = DEFAULTS.exampleLabelStyle;
108
116
  merged.envPresets = normalizeEnvPresets(merged.envPresets, merged.baseUrl);
117
+ merged.docsPath = normalizeDocsPath(process.env.DAXTA_DOCS_PATH || merged.docsPath);
109
118
  merged.controllersRoot = path.isAbsolute(merged.controllersRoot)
110
119
  ? merged.controllersRoot
111
120
  : path.join(cwd, merged.controllersRoot);
@@ -15,10 +15,10 @@ function printDocsReady(hits, operations) {
15
15
  console.log('');
16
16
  console.log(` ${bold('API docs ready')}`);
17
17
  console.log(` ${dim('│')} ${green('✔')} ${cyan(url)} ${dim(`(${hits} hits · ${operations} ops)`)}`);
18
- console.log(` ${dim('│')} ${dim('DAXTA_DOCS=true')} required on app start`);
18
+ console.log(` ${dim('│')} ${dim('DAXTA_DOCS=on')} required on app start`);
19
19
  console.log('');
20
20
  console.log(` ${bold('Next')}`);
21
- console.log(` ${cyan('$')} ${bold('DAXTA_DOCS=true pnpm start:dev')}`);
21
+ console.log(` ${cyan('$')} ${bold('DAXTA_DOCS=on pnpm start:dev')}`);
22
22
  console.log(` ${dim(`open ${url}`)}`);
23
23
  console.log('');
24
24
  }
@@ -1,5 +1,5 @@
1
1
  export type ApiDocsOptions = {
2
- /** URL prefix for the API docs viewer. Default from config (`docsPath`) or `/api-docs`. */
2
+ /** URL prefix for the API docs viewer. Default from config (`docsPath`) / `DAXTA_DOCS_PATH` or `/docs`. */
3
3
  basePath?: string;
4
4
  };
5
5
  type LooseRequest = {
@@ -22,7 +22,7 @@ type LooseResponse = {
22
22
  };
23
23
  export type ApiDocsHandler = (req: LooseRequest, res: LooseResponse, next: (error?: unknown) => void) => void | Promise<void>;
24
24
  /**
25
- * Express / Nest handler that serves generated API docs under `/api-docs`
25
+ * Express / Nest handler that serves generated API docs under `/docs`
26
26
  * (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
27
27
  */
28
28
  export declare function apiDocsHandler(options?: ApiDocsOptions): ApiDocsHandler;
@@ -30,9 +30,11 @@ export declare function apiDocsHandler(options?: ApiDocsOptions): ApiDocsHandler
30
30
  * Mount generated API docs on a Nest / Express app (`app.use(...)`).
31
31
  *
32
32
  * Requires `DAXTA_DOCS` in the environment:
33
- * - missing / empty → throws (app must set it explicitly)
34
- * - `true` | `1` | `yes` | `on` → serve API docs
35
- * - `false` | `0` | `no` | `off` → no-op
33
+ * - missing / empty → throws
34
+ * - `on` → serve docs
35
+ * - `off` → no-op
36
+ *
37
+ * Path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in config.
36
38
  */
37
39
  export declare function apiDocs(app: {
38
40
  use: (...handlers: unknown[]) => unknown;
@@ -96,11 +96,11 @@ async function readRequestJson(req) {
96
96
  }
97
97
  }
98
98
  /**
99
- * Express / Nest handler that serves generated API docs under `/api-docs`
99
+ * Express / Nest handler that serves generated API docs under `/docs`
100
100
  * (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
101
101
  */
102
102
  function apiDocsHandler(options = {}) {
103
- const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/api-docs';
103
+ const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/docs';
104
104
  return async (req, res, next) => {
105
105
  const method = (req.method || 'GET').toUpperCase();
106
106
  const pathname = requestPathname(req);
@@ -193,22 +193,22 @@ function apiDocsHandler(options = {}) {
193
193
  * Mount generated API docs on a Nest / Express app (`app.use(...)`).
194
194
  *
195
195
  * Requires `DAXTA_DOCS` in the environment:
196
- * - missing / empty → throws (app must set it explicitly)
197
- * - `true` | `1` | `yes` | `on` → serve API docs
198
- * - `false` | `0` | `no` | `off` → no-op
196
+ * - missing / empty → throws
197
+ * - `on` → serve docs
198
+ * - `off` → no-op
199
+ *
200
+ * Path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in config.
199
201
  */
200
202
  function apiDocs(app, options = {}) {
201
203
  const raw = process.env.DAXTA_DOCS;
202
204
  if (raw == null || String(raw).trim() === '') {
203
- throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=true to enable API docs, or DAXTA_DOCS=false to disable.');
205
+ throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=on or DAXTA_DOCS=off.');
204
206
  }
205
207
  const normalized = String(raw).trim().toLowerCase();
206
- const enabled = ['1', 'true', 'yes', 'on'].includes(normalized);
207
- const disabled = ['0', 'false', 'no', 'off'].includes(normalized);
208
- if (!enabled && !disabled) {
209
- throw new Error(`DAxTA: invalid DAXTA_DOCS="${raw}". Use true/false (or 1/0).`);
208
+ if (normalized !== 'on' && normalized !== 'off') {
209
+ throw new Error(`DAxTA: invalid DAXTA_DOCS="${raw}". Use on or off.`);
210
210
  }
211
- if (!enabled)
211
+ if (normalized === 'off')
212
212
  return;
213
213
  app.use(apiDocsHandler(options));
214
214
  }
@@ -9,7 +9,7 @@ export declare function getEmptyViewerAssetPath(): string;
9
9
  export declare function readEmptyDocsHtml(): Buffer;
10
10
  export declare function getFaviconAssetPath(): string;
11
11
  export declare function getDocsBasePath(): string;
12
- /** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/api-docs`). */
12
+ /** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/docs`). */
13
13
  export declare function getApiDocUrl(): string;
14
14
  /** Paths and URL for the generated API docs artifact. */
15
15
  export declare function getApiDocs(): {
@@ -85,10 +85,9 @@ function getFaviconAssetPath() {
85
85
  return path.join(__dirname, '..', '..', 'assets', 'favicon.png');
86
86
  }
87
87
  function getDocsBasePath() {
88
- const configured = (0, config_1.getConfig)().docsPath ?? '/api-docs';
89
- return configured.startsWith('/') ? configured.replace(/\/$/, '') || '/api-docs' : `/${configured}`.replace(/\/$/, '');
88
+ return (0, config_1.normalizeDocsPath)(process.env.DAXTA_DOCS_PATH || (0, config_1.getConfig)().docsPath || config_1.DEFAULT_DOCS_PATH);
90
89
  }
91
- /** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/api-docs`). */
90
+ /** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/docs`). */
92
91
  function getApiDocUrl() {
93
92
  const config = (0, config_1.getConfig)();
94
93
  return `${String(config.baseUrl || '').replace(/\/$/, '')}${getDocsBasePath()}`;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@t0.labs/daxta",
3
- "version": "1.1.1",
3
+ "version": "1.1.2",
4
4
  "description": "DAxTA — Tested behavior. Trusted API docs. Generate API documentation from observed test execution.",
5
5
  "license": "MIT",
6
6
  "author": {