@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 +9 -9
- package/assets/empty.html +1 -1
- package/assets/example.html +1 -1
- package/assets/viewer.html +1 -1
- package/dist/cli/install.js +6 -6
- package/dist/config.d.ts +6 -0
- package/dist/config.js +10 -1
- package/dist/jest/reporter.js +2 -2
- package/dist/serve/middleware.d.ts +7 -5
- package/dist/serve/middleware.js +11 -11
- package/dist/serve/paths.d.ts +1 -1
- package/dist/serve/paths.js +2 -3
- package/package.json +1 -1
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 /
|
|
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=
|
|
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=
|
|
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 `/
|
|
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=
|
|
297
|
-
DAXTA_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=
|
|
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
|
|
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
package/assets/example.html
CHANGED
|
@@ -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 || "/
|
|
1546
|
+
const docsPathSuffix = String(viewer.docsPath || "/docs").replace(/\/$/, "") || "/docs";
|
|
1547
1547
|
|
|
1548
1548
|
const inferBaseUrlFromLocation = () => {
|
|
1549
1549
|
if (typeof location === "undefined") return null;
|
package/assets/viewer.html
CHANGED
|
@@ -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 || "/
|
|
1339
|
+
const docsPathSuffix = String(viewer.docsPath || "/docs").replace(/\/$/, "") || "/docs";
|
|
1340
1340
|
|
|
1341
1341
|
const inferBaseUrlFromLocation = () => {
|
|
1342
1342
|
if (typeof location === "undefined") return null;
|
package/dist/cli/install.js
CHANGED
|
@@ -118,7 +118,7 @@ export default defineConfig({
|
|
|
118
118
|
baseUrl: 'http://localhost:3000',
|
|
119
119
|
controllersRoot: 'src',
|
|
120
120
|
outDir: '.daxta/out',
|
|
121
|
-
docsPath: '/
|
|
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
|
|
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=
|
|
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=
|
|
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('/
|
|
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 /
|
|
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: '/
|
|
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);
|
package/dist/jest/reporter.js
CHANGED
|
@@ -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=
|
|
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=
|
|
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 `/
|
|
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 `/
|
|
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
|
|
34
|
-
* - `
|
|
35
|
-
* - `
|
|
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;
|
package/dist/serve/middleware.js
CHANGED
|
@@ -96,11 +96,11 @@ async function readRequestJson(req) {
|
|
|
96
96
|
}
|
|
97
97
|
}
|
|
98
98
|
/**
|
|
99
|
-
* Express / Nest handler that serves generated API docs under `/
|
|
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(/\/$/, '') || '/
|
|
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
|
|
197
|
-
* - `
|
|
198
|
-
* - `
|
|
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=
|
|
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
|
-
|
|
207
|
-
|
|
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 (
|
|
211
|
+
if (normalized === 'off')
|
|
212
212
|
return;
|
|
213
213
|
app.use(apiDocsHandler(options));
|
|
214
214
|
}
|
package/dist/serve/paths.d.ts
CHANGED
|
@@ -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/
|
|
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(): {
|
package/dist/serve/paths.js
CHANGED
|
@@ -85,10 +85,9 @@ function getFaviconAssetPath() {
|
|
|
85
85
|
return path.join(__dirname, '..', '..', 'assets', 'favicon.png');
|
|
86
86
|
}
|
|
87
87
|
function getDocsBasePath() {
|
|
88
|
-
|
|
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/
|
|
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()}`;
|