@t0.labs/daxta 1.1.2 → 1.1.4
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 +623 -86
- package/assets/viewer.html +1027 -191
- package/dist/build/build-spec.js +173 -21
- 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 +41 -9
- 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 +28 -2
- 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 +3 -0
- package/dist/serve/paths.js +12 -0
- package/dist/serve/viewer-store.d.ts +5 -2
- package/dist/serve/viewer-store.js +9 -4
- package/package.json +1 -1
package/dist/config.d.ts
CHANGED
|
@@ -11,6 +11,11 @@ export type SpecInfo = {
|
|
|
11
11
|
/** Named Try-it preset: own baseUrl + optional extra variables (tokens, etc.). */
|
|
12
12
|
export type EnvPreset = {
|
|
13
13
|
baseUrl: string;
|
|
14
|
+
/**
|
|
15
|
+
* Variable name that carries the base URL in Try-it and Postman exports.
|
|
16
|
+
* Default `baseUrl`; set e.g. `ONBOARDING_SERVICE` to match an existing collection.
|
|
17
|
+
*/
|
|
18
|
+
baseUrlKey?: string;
|
|
14
19
|
/** Extra variables merged into the preset (baseUrl wins from EnvPreset.baseUrl). */
|
|
15
20
|
variables?: Record<string, string>;
|
|
16
21
|
};
|
|
@@ -36,6 +41,13 @@ export type DaxtaConfig = {
|
|
|
36
41
|
* Ops like POST …/{id}/lock sit under the parent resource. Default true.
|
|
37
42
|
*/
|
|
38
43
|
treeSkipParams?: boolean;
|
|
44
|
+
/**
|
|
45
|
+
* Fold a leaf folder into its parent when it holds a single operation and no
|
|
46
|
+
* subfolders, so `merchants › tr › POST` becomes `merchants › POST onboard tr merchant`
|
|
47
|
+
* while `external-checkouts` keeps its folder because several ops live there.
|
|
48
|
+
* One level only. Default true.
|
|
49
|
+
*/
|
|
50
|
+
treeCollapseSingle?: boolean;
|
|
39
51
|
treePathOverrides?: Record<string, string[]>;
|
|
40
52
|
/**
|
|
41
53
|
* OpenAPI example + scenario labels:
|
|
@@ -70,12 +82,23 @@ export type DaxtaConfig = {
|
|
|
70
82
|
includeHit?: (method: string, pathTemplate: string, test?: string) => boolean;
|
|
71
83
|
treePathSegments?: (pathTemplate: string) => string[] | undefined;
|
|
72
84
|
};
|
|
73
|
-
export type ResolvedDaxtaConfig = Required<Pick<DaxtaConfig, 'workspace' | 'baseUrl' | 'controllersRoot' | 'outDir' | 'treeLayout' | 'treePathOverrides' | 'treeSkipParams' | 'exampleLabelStyle' | 'port' | 'fieldsFile' | 'docsPath' | 'viewerStoreFile'>> & DaxtaConfig;
|
|
85
|
+
export type ResolvedDaxtaConfig = Required<Pick<DaxtaConfig, 'workspace' | 'baseUrl' | 'controllersRoot' | 'outDir' | 'treeLayout' | 'treePathOverrides' | 'treeSkipParams' | 'treeCollapseSingle' | 'exampleLabelStyle' | 'port' | 'fieldsFile' | 'docsPath' | 'viewerStoreFile'>> & DaxtaConfig;
|
|
74
86
|
export declare const DEFAULT_DOCS_PATH = "/docs";
|
|
75
87
|
export declare function normalizeDocsPath(raw?: string | null): string;
|
|
76
88
|
export declare function defineConfig(config: DaxtaConfig): DaxtaConfig;
|
|
77
89
|
export declare function normalizeTreeLayout(layout: TreeLayout | LegacyTreeLayout | undefined): TreeLayout;
|
|
78
90
|
export declare function resolveConfig(cwd?: string, overrides?: DaxtaConfig): ResolvedDaxtaConfig;
|
|
91
|
+
/**
|
|
92
|
+
* Env name for a base URL when the config does not name it:
|
|
93
|
+
* loopback → local, host keywords (staging/dev/test/qa/sandbox) → that keyword,
|
|
94
|
+
* anything else → first non-generic subdomain, or `production` for plain api.* hosts.
|
|
95
|
+
*/
|
|
96
|
+
export declare function envNameFromUrl(url: string): string;
|
|
97
|
+
/** Unique-ified `{ url, description }` servers for the spec, one per env preset. */
|
|
98
|
+
export declare function serversFromEnvPresets(presets: Record<string, EnvPreset> | undefined, fallbackBaseUrl: string): Array<{
|
|
99
|
+
url: string;
|
|
100
|
+
description: string;
|
|
101
|
+
}>;
|
|
79
102
|
export declare function getConfig(forceReload?: boolean): ResolvedDaxtaConfig;
|
|
80
103
|
export declare function setConfig(config: ResolvedDaxtaConfig): void;
|
|
81
104
|
export declare function resetConfig(): void;
|
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
|
}
|
|
@@ -47,9 +47,34 @@ const path = __importStar(require("path"));
|
|
|
47
47
|
require("reflect-metadata");
|
|
48
48
|
const storage_1 = require("class-transformer/cjs/storage");
|
|
49
49
|
const class_validator_1 = require("class-validator");
|
|
50
|
-
const
|
|
50
|
+
const tsImport = __importStar(require("typescript"));
|
|
51
51
|
const config_1 = require("../config");
|
|
52
52
|
const path_util_1 = require("../path.util");
|
|
53
|
+
function loadTypescript() {
|
|
54
|
+
const mod = tsImport;
|
|
55
|
+
const candidates = [];
|
|
56
|
+
if (mod)
|
|
57
|
+
candidates.push(mod);
|
|
58
|
+
if (mod.default)
|
|
59
|
+
candidates.push(mod.default);
|
|
60
|
+
for (const candidate of candidates) {
|
|
61
|
+
if (typeof candidate.createSourceFile === 'function')
|
|
62
|
+
return candidate;
|
|
63
|
+
}
|
|
64
|
+
try {
|
|
65
|
+
// CJS interop: namespace import can expose enums without compiler APIs.
|
|
66
|
+
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
67
|
+
const req = require('typescript');
|
|
68
|
+
const fromReq = typeof req.createSourceFile === 'function' ? req : req.default;
|
|
69
|
+
if (fromReq && typeof fromReq.createSourceFile === 'function')
|
|
70
|
+
return fromReq;
|
|
71
|
+
}
|
|
72
|
+
catch {
|
|
73
|
+
// ignore — fall through
|
|
74
|
+
}
|
|
75
|
+
throw new Error('Could not load TypeScript compiler API (createSourceFile missing)');
|
|
76
|
+
}
|
|
77
|
+
const ts = loadTypescript();
|
|
53
78
|
function controllerRoot() {
|
|
54
79
|
return (0, config_1.getConfig)().controllersRoot;
|
|
55
80
|
}
|
|
@@ -182,7 +207,8 @@ function loadDto(filePath, exportName) {
|
|
|
182
207
|
}
|
|
183
208
|
function parseController(filePath) {
|
|
184
209
|
const text = (0, fs_1.readFileSync)(filePath, 'utf8');
|
|
185
|
-
const
|
|
210
|
+
const scriptTarget = ts.ScriptTarget?.Latest ?? 99;
|
|
211
|
+
const source = ts.createSourceFile(filePath, text, scriptTarget, true);
|
|
186
212
|
const imports = collectImports(source, filePath);
|
|
187
213
|
const routes = [];
|
|
188
214
|
for (const stmt of source.statements) {
|
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,12 +2,15 @@ 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;
|
|
8
10
|
export declare function getEmptyViewerAssetPath(): string;
|
|
9
11
|
export declare function readEmptyDocsHtml(): Buffer;
|
|
10
12
|
export declare function getFaviconAssetPath(): string;
|
|
13
|
+
export declare function getFaviconLightAssetPath(): string;
|
|
11
14
|
export declare function getDocsBasePath(): string;
|
|
12
15
|
/** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/docs`). */
|
|
13
16
|
export declare function getApiDocUrl(): string;
|
package/dist/serve/paths.js
CHANGED
|
@@ -37,11 +37,13 @@ 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;
|
|
43
44
|
exports.readEmptyDocsHtml = readEmptyDocsHtml;
|
|
44
45
|
exports.getFaviconAssetPath = getFaviconAssetPath;
|
|
46
|
+
exports.getFaviconLightAssetPath = getFaviconLightAssetPath;
|
|
45
47
|
exports.getDocsBasePath = getDocsBasePath;
|
|
46
48
|
exports.getApiDocUrl = getApiDocUrl;
|
|
47
49
|
exports.getApiDocs = getApiDocs;
|
|
@@ -60,6 +62,10 @@ function getSpecJsonPath() {
|
|
|
60
62
|
function getHitsJsonPath() {
|
|
61
63
|
return path.join(getOutDir(), 'hits.json');
|
|
62
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
|
+
}
|
|
63
69
|
/** Try-it env/headers — outside outDir so rebuild does not wipe it. */
|
|
64
70
|
function getViewerStorePath() {
|
|
65
71
|
return (0, config_1.getConfig)().viewerStoreFile;
|
|
@@ -82,8 +88,14 @@ function readEmptyDocsHtml() {
|
|
|
82
88
|
return Buffer.from(EMPTY_DOCS_FALLBACK);
|
|
83
89
|
}
|
|
84
90
|
function getFaviconAssetPath() {
|
|
91
|
+
const dark = path.join(__dirname, '..', '..', 'assets', 'logo-dark.png');
|
|
92
|
+
if ((0, fs_1.existsSync)(dark))
|
|
93
|
+
return dark;
|
|
85
94
|
return path.join(__dirname, '..', '..', 'assets', 'favicon.png');
|
|
86
95
|
}
|
|
96
|
+
function getFaviconLightAssetPath() {
|
|
97
|
+
return path.join(__dirname, '..', '..', 'assets', 'logo-light.png');
|
|
98
|
+
}
|
|
87
99
|
function getDocsBasePath() {
|
|
88
100
|
return (0, config_1.normalizeDocsPath)(process.env.DAXTA_DOCS_PATH || (0, config_1.getConfig)().docsPath || config_1.DEFAULT_DOCS_PATH);
|
|
89
101
|
}
|
|
@@ -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);
|