@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 +123 -55
- package/assets/example.html +584 -93
- package/assets/viewer.html +583 -92
- package/dist/build/build-spec.js +165 -15
- package/dist/catalog/index.d.ts +1 -0
- package/dist/catalog/index.js +23 -10
- package/dist/catalog/it-case.js +2 -0
- package/dist/catalog/test-title.js +7 -5
- package/dist/cli/install.js +18 -16
- package/dist/cli/titles.js +7 -5
- package/dist/cli/tree.js +14 -4
- package/dist/cli/uninstall.js +2 -1
- package/dist/config.d.ts +24 -1
- package/dist/config.js +69 -2
- package/dist/fields/dto-fields.js +42 -6
- package/dist/index.d.ts +2 -2
- package/dist/index.js +5 -1
- package/dist/jest/global-setup.js +1 -0
- package/dist/jest/global-teardown.js +4 -0
- package/dist/jest/reporter.d.ts +2 -0
- package/dist/jest/reporter.js +23 -2
- package/dist/recorder/index.d.ts +6 -0
- package/dist/recorder/index.js +36 -3
- package/dist/serve/index.d.ts +1 -1
- package/dist/serve/index.js +2 -1
- package/dist/serve/middleware.d.ts +3 -4
- package/dist/serve/middleware.js +14 -13
- package/dist/serve/paths.d.ts +2 -0
- package/dist/serve/paths.js +5 -0
- package/dist/serve/viewer-store.d.ts +5 -2
- package/dist/serve/viewer-store.js +9 -4
- package/package.json +2 -2
package/dist/config.js
CHANGED
|
@@ -38,6 +38,8 @@ exports.normalizeDocsPath = normalizeDocsPath;
|
|
|
38
38
|
exports.defineConfig = defineConfig;
|
|
39
39
|
exports.normalizeTreeLayout = normalizeTreeLayout;
|
|
40
40
|
exports.resolveConfig = resolveConfig;
|
|
41
|
+
exports.envNameFromUrl = envNameFromUrl;
|
|
42
|
+
exports.serversFromEnvPresets = serversFromEnvPresets;
|
|
41
43
|
exports.getConfig = getConfig;
|
|
42
44
|
exports.setConfig = setConfig;
|
|
43
45
|
exports.resetConfig = resetConfig;
|
|
@@ -50,6 +52,7 @@ const DEFAULTS = {
|
|
|
50
52
|
outDir: '.daxta/out',
|
|
51
53
|
treeLayout: 'role-resource',
|
|
52
54
|
treeSkipParams: true,
|
|
55
|
+
treeCollapseSingle: true,
|
|
53
56
|
treePathOverrides: {},
|
|
54
57
|
exampleLabelStyle: 'status-title-case',
|
|
55
58
|
port: 5199,
|
|
@@ -111,6 +114,8 @@ function resolveConfig(cwd = process.cwd(), overrides) {
|
|
|
111
114
|
merged.treeLayout = normalizeTreeLayout(merged.treeLayout);
|
|
112
115
|
if (merged.treeSkipParams == null)
|
|
113
116
|
merged.treeSkipParams = DEFAULTS.treeSkipParams;
|
|
117
|
+
if (merged.treeCollapseSingle == null)
|
|
118
|
+
merged.treeCollapseSingle = DEFAULTS.treeCollapseSingle;
|
|
114
119
|
if (merged.exampleLabelStyle == null)
|
|
115
120
|
merged.exampleLabelStyle = DEFAULTS.exampleLabelStyle;
|
|
116
121
|
merged.envPresets = normalizeEnvPresets(merged.envPresets, merged.baseUrl);
|
|
@@ -125,6 +130,62 @@ function resolveConfig(cwd = process.cwd(), overrides) {
|
|
|
125
130
|
: path.join(cwd, merged.viewerStoreFile);
|
|
126
131
|
return merged;
|
|
127
132
|
}
|
|
133
|
+
/**
|
|
134
|
+
* Env name for a base URL when the config does not name it:
|
|
135
|
+
* loopback → local, host keywords (staging/dev/test/qa/sandbox) → that keyword,
|
|
136
|
+
* anything else → first non-generic subdomain, or `production` for plain api.* hosts.
|
|
137
|
+
*/
|
|
138
|
+
function envNameFromUrl(url) {
|
|
139
|
+
let host = String(url || '').trim();
|
|
140
|
+
try {
|
|
141
|
+
host = new URL(host).hostname;
|
|
142
|
+
}
|
|
143
|
+
catch {
|
|
144
|
+
host = host.replace(/^[a-z]+:\/\//i, '').split('/')[0].split(':')[0];
|
|
145
|
+
}
|
|
146
|
+
host = host.toLowerCase();
|
|
147
|
+
if (!host)
|
|
148
|
+
return 'local';
|
|
149
|
+
if (host === 'localhost' || host === '127.0.0.1' || host === '0.0.0.0' || host === '::1' || host.endsWith('.local')) {
|
|
150
|
+
return 'local';
|
|
151
|
+
}
|
|
152
|
+
const keywords = [
|
|
153
|
+
[/\bstag(e|ing)\b/, 'staging'],
|
|
154
|
+
[/\b(dev|development)\b/, 'development'],
|
|
155
|
+
[/\b(test|testing)\b/, 'test'],
|
|
156
|
+
[/\bqa\b/, 'qa'],
|
|
157
|
+
[/\bsandbox\b/, 'sandbox'],
|
|
158
|
+
[/\b(preprod|pre-prod|uat)\b/, 'uat'],
|
|
159
|
+
[/\b(prod|production)\b/, 'production'],
|
|
160
|
+
];
|
|
161
|
+
const labels = host.split('.');
|
|
162
|
+
for (const [pattern, name] of keywords) {
|
|
163
|
+
if (labels.some((label) => pattern.test(label)))
|
|
164
|
+
return name;
|
|
165
|
+
}
|
|
166
|
+
// Only subdomains name an environment; the registrable domain is the product itself.
|
|
167
|
+
const generic = new Set(['api', 'www', 'app', 'gateway', 'edge']);
|
|
168
|
+
const subdomains = labels.slice(0, -2).filter((label) => label && !generic.has(label));
|
|
169
|
+
return subdomains[0] || 'production';
|
|
170
|
+
}
|
|
171
|
+
/** Unique-ified `{ url, description }` servers for the spec, one per env preset. */
|
|
172
|
+
function serversFromEnvPresets(presets, fallbackBaseUrl) {
|
|
173
|
+
const normalized = normalizeEnvPresets(presets, fallbackBaseUrl);
|
|
174
|
+
const seen = new Set();
|
|
175
|
+
const servers = [];
|
|
176
|
+
for (const [name, preset] of Object.entries(normalized)) {
|
|
177
|
+
const url = String(preset.baseUrl).replace(/\/$/, '');
|
|
178
|
+
if (!url || seen.has(url))
|
|
179
|
+
continue;
|
|
180
|
+
seen.add(url);
|
|
181
|
+
servers.push({ url, description: name });
|
|
182
|
+
}
|
|
183
|
+
if (!servers.length) {
|
|
184
|
+
const url = String(fallbackBaseUrl).replace(/\/$/, '') || 'http://localhost:3000';
|
|
185
|
+
servers.push({ url, description: envNameFromUrl(url) });
|
|
186
|
+
}
|
|
187
|
+
return servers;
|
|
188
|
+
}
|
|
128
189
|
function normalizeEnvPresets(presets, fallbackBaseUrl) {
|
|
129
190
|
const input = presets && typeof presets === 'object' ? presets : {};
|
|
130
191
|
const out = {};
|
|
@@ -140,10 +201,16 @@ function normalizeEnvPresets(presets, fallbackBaseUrl) {
|
|
|
140
201
|
variables[key] = String(value ?? '');
|
|
141
202
|
}
|
|
142
203
|
}
|
|
143
|
-
|
|
204
|
+
const baseUrlKey = typeof preset.baseUrlKey === 'string' ? preset.baseUrlKey.trim() : '';
|
|
205
|
+
out[name] = {
|
|
206
|
+
baseUrl,
|
|
207
|
+
...(baseUrlKey && baseUrlKey !== 'baseUrl' ? { baseUrlKey } : {}),
|
|
208
|
+
...(Object.keys(variables).length ? { variables } : {}),
|
|
209
|
+
};
|
|
144
210
|
}
|
|
145
211
|
if (!Object.keys(out).length) {
|
|
146
|
-
|
|
212
|
+
const baseUrl = String(fallbackBaseUrl).replace(/\/$/, '') || 'http://localhost:3000';
|
|
213
|
+
out[envNameFromUrl(baseUrl)] = { baseUrl };
|
|
147
214
|
}
|
|
148
215
|
return out;
|
|
149
216
|
}
|
|
@@ -43,6 +43,7 @@ exports.dtoRequired = dtoRequired;
|
|
|
43
43
|
* only to read reflect-metadata / class-validator / class-transformer.
|
|
44
44
|
*/
|
|
45
45
|
const fs_1 = require("fs");
|
|
46
|
+
const module_1 = require("module");
|
|
46
47
|
const path = __importStar(require("path"));
|
|
47
48
|
require("reflect-metadata");
|
|
48
49
|
const storage_1 = require("class-transformer/cjs/storage");
|
|
@@ -50,15 +51,48 @@ const class_validator_1 = require("class-validator");
|
|
|
50
51
|
const tsImport = __importStar(require("typescript"));
|
|
51
52
|
const config_1 = require("../config");
|
|
52
53
|
const path_util_1 = require("../path.util");
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
54
|
+
let ts;
|
|
55
|
+
let tsResolved;
|
|
56
|
+
function withCompilerApi(candidate) {
|
|
57
|
+
const mod = candidate;
|
|
58
|
+
if (mod && typeof mod.createSourceFile === 'function')
|
|
56
59
|
return mod;
|
|
57
|
-
if (mod
|
|
60
|
+
if (mod?.default && typeof mod.default.createSourceFile === 'function')
|
|
58
61
|
return mod.default;
|
|
59
|
-
return
|
|
62
|
+
return undefined;
|
|
63
|
+
}
|
|
64
|
+
function resolveTypescript() {
|
|
65
|
+
const direct = withCompilerApi(tsImport);
|
|
66
|
+
if (direct)
|
|
67
|
+
return direct;
|
|
68
|
+
// A hoisted copy can be the native TS 7 build, which ships a reduced JS surface
|
|
69
|
+
// without createSourceFile. Fall back to whatever the host project installed.
|
|
70
|
+
for (const from of [process.cwd(), __dirname]) {
|
|
71
|
+
try {
|
|
72
|
+
const loaded = (0, module_1.createRequire)(path.join(from, 'index.js'))('typescript');
|
|
73
|
+
const usable = withCompilerApi(loaded);
|
|
74
|
+
if (usable)
|
|
75
|
+
return usable;
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
// keep looking
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
return null;
|
|
82
|
+
}
|
|
83
|
+
/** Controller parsing is best-effort: without a usable compiler API we skip it. */
|
|
84
|
+
function ensureTypescript() {
|
|
85
|
+
if (tsResolved === undefined) {
|
|
86
|
+
tsResolved = resolveTypescript();
|
|
87
|
+
if (!tsResolved) {
|
|
88
|
+
console.warn('DAxTA: TypeScript compiler API unavailable (needs typescript >=4.9 <7) — skipping controller parsing; required/optional flags will be omitted.');
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
if (!tsResolved)
|
|
92
|
+
return false;
|
|
93
|
+
ts = tsResolved;
|
|
94
|
+
return true;
|
|
60
95
|
}
|
|
61
|
-
const ts = loadTypescript();
|
|
62
96
|
function controllerRoot() {
|
|
63
97
|
return (0, config_1.getConfig)().controllersRoot;
|
|
64
98
|
}
|
|
@@ -276,6 +310,8 @@ function parseController(filePath) {
|
|
|
276
310
|
function getRoutes() {
|
|
277
311
|
if (routeCache)
|
|
278
312
|
return routeCache;
|
|
313
|
+
if (!ensureTypescript())
|
|
314
|
+
return (routeCache = []);
|
|
279
315
|
const files = walkFiles(controllerRoot(), '.controller.ts');
|
|
280
316
|
routeCache = files.flatMap((file) => {
|
|
281
317
|
try {
|
package/dist/index.d.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
export { defineConfig, getConfig, resolveConfig, normalizeTreeLayout, type DaxtaConfig, type EnvPreset, type TreeLayout, type ExampleLabelStyle, type SpecInfo } from './config';
|
|
2
2
|
export { generateApiDocs, buildDaxtaSpec, buildOpenApi, loadHits, type BuildResult, type Scenario } from './build/build-spec';
|
|
3
3
|
export { rebuildFromDisk, flushAndRebuild, clearPartialMarker, touchPartialMarker } from './build/incremental';
|
|
4
|
-
export { install, flush, clearWorkerHits, getHits, type RecordedHit } from './recorder';
|
|
4
|
+
export { install, flush, clearWorkerHits, clearRunMarker, startRun, readRunId, getHits, type RecordedHit } from './recorder';
|
|
5
5
|
export { dtoRequired, type FieldLocation } from './fields/dto-fields';
|
|
6
6
|
export { buildFieldsFile, writeFieldsFile, readFieldsFile, type FieldsFile } from './fields/export-fields';
|
|
7
|
-
export { apiDocs, apiDocsHandler, serveApiDocs, getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
|
|
7
|
+
export { apiDocs, apiDocsHandler, docsEnabled, serveApiDocs, getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
|
|
8
8
|
export { runInteractiveCall, runFileCall, executeCall, type CallValues } from './call';
|
|
9
9
|
export { apiTitle, parseOperationLabel, suggestOperationTitles, suggestOperationTitleResult, formatTestTitle, isValidItCase, suggestItCases, docsScenarioClause, type FieldDoc, type OperationDoc, } from './catalog';
|
|
10
10
|
export { installDaxta, type InstallOptions } from './cli/install';
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.serveApiDocs = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.generateApiDocs = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
|
|
3
|
+
exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.serveApiDocs = exports.docsEnabled = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.readRunId = exports.startRun = exports.clearRunMarker = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.generateApiDocs = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
|
|
4
4
|
var config_1 = require("./config");
|
|
5
5
|
Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });
|
|
6
6
|
Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return config_1.getConfig; } });
|
|
@@ -20,6 +20,9 @@ var recorder_1 = require("./recorder");
|
|
|
20
20
|
Object.defineProperty(exports, "install", { enumerable: true, get: function () { return recorder_1.install; } });
|
|
21
21
|
Object.defineProperty(exports, "flush", { enumerable: true, get: function () { return recorder_1.flush; } });
|
|
22
22
|
Object.defineProperty(exports, "clearWorkerHits", { enumerable: true, get: function () { return recorder_1.clearWorkerHits; } });
|
|
23
|
+
Object.defineProperty(exports, "clearRunMarker", { enumerable: true, get: function () { return recorder_1.clearRunMarker; } });
|
|
24
|
+
Object.defineProperty(exports, "startRun", { enumerable: true, get: function () { return recorder_1.startRun; } });
|
|
25
|
+
Object.defineProperty(exports, "readRunId", { enumerable: true, get: function () { return recorder_1.readRunId; } });
|
|
23
26
|
Object.defineProperty(exports, "getHits", { enumerable: true, get: function () { return recorder_1.getHits; } });
|
|
24
27
|
var dto_fields_1 = require("./fields/dto-fields");
|
|
25
28
|
Object.defineProperty(exports, "dtoRequired", { enumerable: true, get: function () { return dto_fields_1.dtoRequired; } });
|
|
@@ -30,6 +33,7 @@ Object.defineProperty(exports, "readFieldsFile", { enumerable: true, get: functi
|
|
|
30
33
|
var serve_1 = require("./serve");
|
|
31
34
|
Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return serve_1.apiDocs; } });
|
|
32
35
|
Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return serve_1.apiDocsHandler; } });
|
|
36
|
+
Object.defineProperty(exports, "docsEnabled", { enumerable: true, get: function () { return serve_1.docsEnabled; } });
|
|
33
37
|
Object.defineProperty(exports, "serveApiDocs", { enumerable: true, get: function () { return serve_1.serveApiDocs; } });
|
|
34
38
|
Object.defineProperty(exports, "getApiDocs", { enumerable: true, get: function () { return serve_1.getApiDocs; } });
|
|
35
39
|
Object.defineProperty(exports, "getApiDocUrl", { enumerable: true, get: function () { return serve_1.getApiDocUrl; } });
|
|
@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
3
3
|
exports.default = daxtaGlobalTeardown;
|
|
4
4
|
const incremental_1 = require("../build/incremental");
|
|
5
5
|
const build_spec_1 = require("../build/build-spec");
|
|
6
|
+
const recorder_1 = require("../recorder");
|
|
6
7
|
/**
|
|
7
8
|
* Optional jest globalTeardown — silent generate only.
|
|
8
9
|
* API docs ready is printed by the Jest reporter so we don't own the test process.
|
|
@@ -15,4 +16,7 @@ async function daxtaGlobalTeardown() {
|
|
|
15
16
|
catch {
|
|
16
17
|
// never fail teardown
|
|
17
18
|
}
|
|
19
|
+
finally {
|
|
20
|
+
(0, recorder_1.clearRunMarker)();
|
|
21
|
+
}
|
|
18
22
|
}
|
package/dist/jest/reporter.d.ts
CHANGED
|
@@ -3,6 +3,8 @@
|
|
|
3
3
|
* During the run we only record hits (superagent hook + flush); no mid-run rebuilds.
|
|
4
4
|
*/
|
|
5
5
|
declare class DaxtaJestReporter {
|
|
6
|
+
/** Stamp the run before workers start so this run's docs only reflect this run's traffic. */
|
|
7
|
+
onRunStart(): void;
|
|
6
8
|
onRunComplete(): void;
|
|
7
9
|
}
|
|
8
10
|
export = DaxtaJestReporter;
|
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('
|
|
18
|
+
console.log(` ${dim('│')} ${dim('served when NODE_ENV is dev/test/staging')}`);
|
|
19
19
|
console.log('');
|
|
20
20
|
console.log(` ${bold('Next')}`);
|
|
21
|
-
console.log(` ${cyan('$')} ${bold('
|
|
21
|
+
console.log(` ${cyan('$')} ${bold('pnpm start:dev')}`);
|
|
22
22
|
console.log(` ${dim(`open ${url}`)}`);
|
|
23
23
|
console.log('');
|
|
24
24
|
}
|
|
@@ -31,6 +31,18 @@ function printDocsReady(hits, operations) {
|
|
|
31
31
|
* During the run we only record hits (superagent hook + flush); no mid-run rebuilds.
|
|
32
32
|
*/
|
|
33
33
|
class DaxtaJestReporter {
|
|
34
|
+
/** Stamp the run before workers start so this run's docs only reflect this run's traffic. */
|
|
35
|
+
onRunStart() {
|
|
36
|
+
try {
|
|
37
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
38
|
+
const recorder = require('../recorder');
|
|
39
|
+
recorder.clearWorkerHits();
|
|
40
|
+
recorder.startRun();
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
// never fail the test run
|
|
44
|
+
}
|
|
45
|
+
}
|
|
34
46
|
onRunComplete() {
|
|
35
47
|
try {
|
|
36
48
|
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
@@ -50,6 +62,15 @@ class DaxtaJestReporter {
|
|
|
50
62
|
catch {
|
|
51
63
|
// never fail the test run
|
|
52
64
|
}
|
|
65
|
+
finally {
|
|
66
|
+
try {
|
|
67
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
68
|
+
require('../recorder').clearRunMarker();
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
// ignore
|
|
72
|
+
}
|
|
73
|
+
}
|
|
53
74
|
}
|
|
54
75
|
}
|
|
55
76
|
module.exports = DaxtaJestReporter;
|
package/dist/recorder/index.d.ts
CHANGED
|
@@ -10,6 +10,12 @@ export type RecordedHit = {
|
|
|
10
10
|
test?: string;
|
|
11
11
|
};
|
|
12
12
|
export declare function install(): void;
|
|
13
|
+
/** Hit files carry the run id so a later build can never pick up an earlier run's traffic. */
|
|
14
|
+
export declare const HIT_FILE_PATTERN: RegExp;
|
|
15
|
+
export declare function readRunId(): string | null;
|
|
16
|
+
/** Called once per Jest run (global setup) so every worker tags its hits identically. */
|
|
17
|
+
export declare function startRun(): string;
|
|
18
|
+
export declare function clearRunMarker(): void;
|
|
13
19
|
export declare function flush(): void;
|
|
14
20
|
export declare function clearWorkerHits(): void;
|
|
15
21
|
export declare function getHits(): RecordedHit[];
|
package/dist/recorder/index.js
CHANGED
|
@@ -33,7 +33,11 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.HIT_FILE_PATTERN = void 0;
|
|
36
37
|
exports.install = install;
|
|
38
|
+
exports.readRunId = readRunId;
|
|
39
|
+
exports.startRun = startRun;
|
|
40
|
+
exports.clearRunMarker = clearRunMarker;
|
|
37
41
|
exports.flush = flush;
|
|
38
42
|
exports.clearWorkerHits = clearWorkerHits;
|
|
39
43
|
exports.getHits = getHits;
|
|
@@ -41,6 +45,7 @@ const fs_1 = require("fs");
|
|
|
41
45
|
const module_1 = require("module");
|
|
42
46
|
const path = __importStar(require("path"));
|
|
43
47
|
const config_1 = require("../config");
|
|
48
|
+
const paths_1 = require("../serve/paths");
|
|
44
49
|
const path_util_1 = require("../path.util");
|
|
45
50
|
const g = globalThis;
|
|
46
51
|
const hits = (g.__DAXTA_HITS__ ??= []);
|
|
@@ -152,9 +157,38 @@ function install() {
|
|
|
152
157
|
process.once('exit', flushSafe);
|
|
153
158
|
}
|
|
154
159
|
}
|
|
160
|
+
/** Hit files carry the run id so a later build can never pick up an earlier run's traffic. */
|
|
161
|
+
exports.HIT_FILE_PATTERN = /^hits-(?:r([A-Za-z0-9]+)-)?w[^-]+-p\d+\.json$/;
|
|
162
|
+
function readRunId() {
|
|
163
|
+
try {
|
|
164
|
+
const marker = JSON.parse((0, fs_1.readFileSync)((0, paths_1.getRunMarkerPath)(), 'utf8'));
|
|
165
|
+
return typeof marker.runId === 'string' && marker.runId ? marker.runId : null;
|
|
166
|
+
}
|
|
167
|
+
catch {
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
/** Called once per Jest run (global setup) so every worker tags its hits identically. */
|
|
172
|
+
function startRun() {
|
|
173
|
+
const dir = outDir();
|
|
174
|
+
(0, fs_1.mkdirSync)(dir, { recursive: true });
|
|
175
|
+
const runId = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
|
|
176
|
+
(0, fs_1.writeFileSync)((0, paths_1.getRunMarkerPath)(), `${JSON.stringify({ runId, startedAt: new Date().toISOString() }, null, 2)}\n`);
|
|
177
|
+
return runId;
|
|
178
|
+
}
|
|
179
|
+
function clearRunMarker() {
|
|
180
|
+
try {
|
|
181
|
+
(0, fs_1.rmSync)((0, paths_1.getRunMarkerPath)());
|
|
182
|
+
}
|
|
183
|
+
catch {
|
|
184
|
+
// ignore
|
|
185
|
+
}
|
|
186
|
+
}
|
|
155
187
|
function hitFilePath() {
|
|
156
188
|
const workerId = process.env.JEST_WORKER_ID ?? '0';
|
|
157
|
-
|
|
189
|
+
const runId = readRunId();
|
|
190
|
+
const prefix = runId ? `hits-r${runId}-` : 'hits-';
|
|
191
|
+
return path.join(outDir(), `${prefix}w${workerId}-p${process.pid}.json`);
|
|
158
192
|
}
|
|
159
193
|
function flush() {
|
|
160
194
|
const dir = outDir();
|
|
@@ -166,9 +200,8 @@ function clearWorkerHits() {
|
|
|
166
200
|
if (!(0, fs_1.existsSync)(dir))
|
|
167
201
|
return;
|
|
168
202
|
for (const fileName of (0, fs_1.readdirSync)(dir)) {
|
|
169
|
-
if (
|
|
203
|
+
if (exports.HIT_FILE_PATTERN.test(fileName))
|
|
170
204
|
(0, fs_1.rmSync)(path.join(dir, fileName));
|
|
171
|
-
}
|
|
172
205
|
}
|
|
173
206
|
}
|
|
174
207
|
function getHits() {
|
package/dist/serve/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import * as http from 'http';
|
|
2
|
-
export { apiDocs, apiDocsHandler, type ApiDocsHandler, type ApiDocsOptions } from './middleware';
|
|
2
|
+
export { apiDocs, apiDocsHandler, docsEnabled, type ApiDocsHandler, type ApiDocsOptions } from './middleware';
|
|
3
3
|
export { getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath } from './paths';
|
|
4
4
|
/** Standalone API docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
5
5
|
export declare function serveApiDocs(options?: {
|
package/dist/serve/index.js
CHANGED
|
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.apiDocsHandler = exports.apiDocs = void 0;
|
|
36
|
+
exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.docsEnabled = exports.apiDocsHandler = exports.apiDocs = void 0;
|
|
37
37
|
exports.serveApiDocs = serveApiDocs;
|
|
38
38
|
const fs_1 = require("fs");
|
|
39
39
|
const http = __importStar(require("http"));
|
|
@@ -46,6 +46,7 @@ const viewer_store_1 = require("./viewer-store");
|
|
|
46
46
|
var middleware_1 = require("./middleware");
|
|
47
47
|
Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return middleware_1.apiDocs; } });
|
|
48
48
|
Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return middleware_1.apiDocsHandler; } });
|
|
49
|
+
Object.defineProperty(exports, "docsEnabled", { enumerable: true, get: function () { return middleware_1.docsEnabled; } });
|
|
49
50
|
var paths_2 = require("./paths");
|
|
50
51
|
Object.defineProperty(exports, "getApiDocs", { enumerable: true, get: function () { return paths_2.getApiDocs; } });
|
|
51
52
|
Object.defineProperty(exports, "getApiDocUrl", { enumerable: true, get: function () { return paths_2.getApiDocUrl; } });
|
|
@@ -26,13 +26,12 @@ export type ApiDocsHandler = (req: LooseRequest, res: LooseResponse, next: (erro
|
|
|
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;
|
|
29
|
+
/** Docs follow `NODE_ENV`, and stay closed unless it names a known working env. */
|
|
30
|
+
export declare function docsEnabled(): boolean;
|
|
29
31
|
/**
|
|
30
32
|
* Mount generated API docs on a Nest / Express app (`app.use(...)`).
|
|
31
33
|
*
|
|
32
|
-
*
|
|
33
|
-
* - missing / empty → throws
|
|
34
|
-
* - `on` → serve docs
|
|
35
|
-
* - `off` → no-op
|
|
34
|
+
* Served only when `NODE_ENV` is dev, development, test, sta or staging.
|
|
36
35
|
*
|
|
37
36
|
* Path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in config.
|
|
38
37
|
*/
|
package/dist/serve/middleware.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.apiDocsHandler = apiDocsHandler;
|
|
4
|
+
exports.docsEnabled = docsEnabled;
|
|
4
5
|
exports.apiDocs = apiDocs;
|
|
5
6
|
const fs_1 = require("fs");
|
|
6
7
|
const paths_1 = require("./paths");
|
|
@@ -189,26 +190,26 @@ function apiDocsHandler(options = {}) {
|
|
|
189
190
|
});
|
|
190
191
|
};
|
|
191
192
|
}
|
|
193
|
+
/**
|
|
194
|
+
* `NODE_ENV` values that open the docs. The list is deliberately closed: an
|
|
195
|
+
* unset or unrecognised `NODE_ENV` keeps the docs off so a misconfigured
|
|
196
|
+
* deployment never exposes them.
|
|
197
|
+
*/
|
|
198
|
+
const WORKING_ENVS = new Set(['dev', 'development', 'test', 'sta', 'staging']);
|
|
199
|
+
/** Docs follow `NODE_ENV`, and stay closed unless it names a known working env. */
|
|
200
|
+
function docsEnabled() {
|
|
201
|
+
const nodeEnv = String(process.env.NODE_ENV ?? '').trim().toLowerCase();
|
|
202
|
+
return WORKING_ENVS.has(nodeEnv);
|
|
203
|
+
}
|
|
192
204
|
/**
|
|
193
205
|
* Mount generated API docs on a Nest / Express app (`app.use(...)`).
|
|
194
206
|
*
|
|
195
|
-
*
|
|
196
|
-
* - missing / empty → throws
|
|
197
|
-
* - `on` → serve docs
|
|
198
|
-
* - `off` → no-op
|
|
207
|
+
* Served only when `NODE_ENV` is dev, development, test, sta or staging.
|
|
199
208
|
*
|
|
200
209
|
* Path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in config.
|
|
201
210
|
*/
|
|
202
211
|
function apiDocs(app, options = {}) {
|
|
203
|
-
|
|
204
|
-
if (raw == null || String(raw).trim() === '') {
|
|
205
|
-
throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=on or DAXTA_DOCS=off.');
|
|
206
|
-
}
|
|
207
|
-
const normalized = String(raw).trim().toLowerCase();
|
|
208
|
-
if (normalized !== 'on' && normalized !== 'off') {
|
|
209
|
-
throw new Error(`DAxTA: invalid DAXTA_DOCS="${raw}". Use on or off.`);
|
|
210
|
-
}
|
|
211
|
-
if (normalized === 'off')
|
|
212
|
+
if (!docsEnabled())
|
|
212
213
|
return;
|
|
213
214
|
app.use(apiDocsHandler(options));
|
|
214
215
|
}
|
package/dist/serve/paths.d.ts
CHANGED
|
@@ -2,6 +2,8 @@ export declare function getOutDir(): string;
|
|
|
2
2
|
export declare function getHtmlPath(): string;
|
|
3
3
|
export declare function getSpecJsonPath(): string;
|
|
4
4
|
export declare function getHitsJsonPath(): string;
|
|
5
|
+
/** Marker written by the Jest global setup; scopes hit files to the current run. */
|
|
6
|
+
export declare function getRunMarkerPath(): string;
|
|
5
7
|
/** Try-it env/headers — outside outDir so rebuild does not wipe it. */
|
|
6
8
|
export declare function getViewerStorePath(): string;
|
|
7
9
|
export declare function getViewerAssetPath(): string;
|
package/dist/serve/paths.js
CHANGED
|
@@ -37,6 +37,7 @@ exports.getOutDir = getOutDir;
|
|
|
37
37
|
exports.getHtmlPath = getHtmlPath;
|
|
38
38
|
exports.getSpecJsonPath = getSpecJsonPath;
|
|
39
39
|
exports.getHitsJsonPath = getHitsJsonPath;
|
|
40
|
+
exports.getRunMarkerPath = getRunMarkerPath;
|
|
40
41
|
exports.getViewerStorePath = getViewerStorePath;
|
|
41
42
|
exports.getViewerAssetPath = getViewerAssetPath;
|
|
42
43
|
exports.getEmptyViewerAssetPath = getEmptyViewerAssetPath;
|
|
@@ -61,6 +62,10 @@ function getSpecJsonPath() {
|
|
|
61
62
|
function getHitsJsonPath() {
|
|
62
63
|
return path.join(getOutDir(), 'hits.json');
|
|
63
64
|
}
|
|
65
|
+
/** Marker written by the Jest global setup; scopes hit files to the current run. */
|
|
66
|
+
function getRunMarkerPath() {
|
|
67
|
+
return path.join(getOutDir(), 'run.json');
|
|
68
|
+
}
|
|
64
69
|
/** Try-it env/headers — outside outDir so rebuild does not wipe it. */
|
|
65
70
|
function getViewerStorePath() {
|
|
66
71
|
return (0, config_1.getConfig)().viewerStoreFile;
|
|
@@ -5,6 +5,8 @@ export type ViewerStoreRow = {
|
|
|
5
5
|
export type ViewerEnvConfig = {
|
|
6
6
|
variables: ViewerStoreRow[];
|
|
7
7
|
headerGroups: Record<string, ViewerStoreRow[]>;
|
|
8
|
+
/** Name of the variable holding the base URL — renameable, e.g. `ONBOARDING_SERVICE`. */
|
|
9
|
+
baseUrlKey?: string;
|
|
8
10
|
};
|
|
9
11
|
export type ViewerEnvStore = {
|
|
10
12
|
activeEnv: string;
|
|
@@ -16,7 +18,8 @@ export declare function normalizeViewerEnvStore(raw: unknown): ViewerEnvStore |
|
|
|
16
18
|
export declare function readViewerEnvStore(): ViewerEnvStore | null;
|
|
17
19
|
export declare function writeViewerEnvStore(raw: unknown): ViewerEnvStore;
|
|
18
20
|
/**
|
|
19
|
-
* If viewer-store.json is missing, seed it from
|
|
20
|
-
* (
|
|
21
|
+
* If viewer-store.json is missing, seed it from the resolved env presets
|
|
22
|
+
* (derived from baseUrl, plus any `envPresets` overrides in daxta.config).
|
|
23
|
+
* Does not overwrite an existing file.
|
|
21
24
|
*/
|
|
22
25
|
export declare function ensureViewerStoreSeeded(): string | null;
|
|
@@ -72,9 +72,11 @@ function normalizeViewerEnvStore(raw) {
|
|
|
72
72
|
if (!Object.keys(headerGroups).length) {
|
|
73
73
|
headerGroups.default = [{ key: 'content-type', value: 'application/json' }];
|
|
74
74
|
}
|
|
75
|
+
const baseUrlKey = typeof envObj.baseUrlKey === 'string' ? envObj.baseUrlKey.trim() : '';
|
|
75
76
|
envs[name] = {
|
|
76
77
|
variables: normalizeRows(envObj.variables),
|
|
77
78
|
headerGroups,
|
|
79
|
+
...(baseUrlKey && baseUrlKey !== 'baseUrl' ? { baseUrlKey } : {}),
|
|
78
80
|
};
|
|
79
81
|
}
|
|
80
82
|
if (!Object.keys(envs).length)
|
|
@@ -105,8 +107,9 @@ function writeViewerEnvStore(raw) {
|
|
|
105
107
|
return store;
|
|
106
108
|
}
|
|
107
109
|
/**
|
|
108
|
-
* If viewer-store.json is missing, seed it from
|
|
109
|
-
* (
|
|
110
|
+
* If viewer-store.json is missing, seed it from the resolved env presets
|
|
111
|
+
* (derived from baseUrl, plus any `envPresets` overrides in daxta.config).
|
|
112
|
+
* Does not overwrite an existing file.
|
|
110
113
|
*/
|
|
111
114
|
function ensureViewerStoreSeeded() {
|
|
112
115
|
const filePath = (0, paths_1.getViewerStorePath)();
|
|
@@ -116,15 +119,17 @@ function ensureViewerStoreSeeded() {
|
|
|
116
119
|
const presets = config.envPresets ?? { local: { baseUrl: config.baseUrl } };
|
|
117
120
|
const envs = {};
|
|
118
121
|
for (const [name, preset] of Object.entries(presets)) {
|
|
119
|
-
const
|
|
122
|
+
const baseUrlKey = preset.baseUrlKey?.trim() || 'baseUrl';
|
|
123
|
+
const variables = [{ key: baseUrlKey, value: String(preset.baseUrl || config.baseUrl) }];
|
|
120
124
|
for (const [key, value] of Object.entries(preset.variables ?? {})) {
|
|
121
|
-
if (!key || key ===
|
|
125
|
+
if (!key || key === baseUrlKey)
|
|
122
126
|
continue;
|
|
123
127
|
variables.push({ key, value: String(value ?? '') });
|
|
124
128
|
}
|
|
125
129
|
envs[name] = {
|
|
126
130
|
variables,
|
|
127
131
|
headerGroups: { default: [{ key: 'content-type', value: 'application/json' }] },
|
|
132
|
+
...(baseUrlKey !== 'baseUrl' ? { baseUrlKey } : {}),
|
|
128
133
|
};
|
|
129
134
|
}
|
|
130
135
|
const names = Object.keys(envs);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@t0.labs/daxta",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.5",
|
|
4
4
|
"description": "DAxTA — Tested behavior. Trusted API docs. Generate API documentation from observed test execution.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": {
|
|
@@ -78,7 +78,7 @@
|
|
|
78
78
|
"class-transformer": ">=0.5.0",
|
|
79
79
|
"class-validator": ">=0.14.0",
|
|
80
80
|
"reflect-metadata": ">=0.1.13",
|
|
81
|
-
"typescript": ">=4.9.0",
|
|
81
|
+
"typescript": ">=4.9.0 <7",
|
|
82
82
|
"jest": ">=27"
|
|
83
83
|
},
|
|
84
84
|
"peerDependenciesMeta": {
|