@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/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
- out[name] = Object.keys(variables).length ? { baseUrl, variables } : { baseUrl };
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
- out.local = { baseUrl: String(fallbackBaseUrl).replace(/\/$/, '') || 'http://localhost:3000' };
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
- function loadTypescript() {
54
- const mod = tsImport;
55
- if (mod.ScriptTarget && mod.ScriptTarget.Latest != null)
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.default?.ScriptTarget && mod.default.ScriptTarget.Latest != null)
60
+ if (mod?.default && typeof mod.default.createSourceFile === 'function')
58
61
  return mod.default;
59
- return mod;
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; } });
@@ -7,6 +7,7 @@ const scan_1 = require("../titles/scan");
7
7
  const ui_1 = require("../cli/ui");
8
8
  async function daxtaGlobalSetup() {
9
9
  (0, recorder_1.clearWorkerHits)();
10
+ (0, recorder_1.startRun)();
10
11
  try {
11
12
  if (process.env.DAXTA_TITLE_CHECK === 'off')
12
13
  return;
@@ -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
  }
@@ -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;
@@ -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=on')} required on app start`);
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('DAXTA_DOCS=on pnpm start:dev')}`);
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;
@@ -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[];
@@ -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
- return path.join(outDir(), `hits-w${workerId}-p${process.pid}.json`);
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 (fileName.startsWith('hits-w') && fileName.endsWith('.json')) {
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() {
@@ -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?: {
@@ -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
- * Requires `DAXTA_DOCS` in the environment:
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
  */
@@ -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
- * Requires `DAXTA_DOCS` in the environment:
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
- const raw = process.env.DAXTA_DOCS;
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
  }
@@ -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;
@@ -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 `envPresets` in daxta.config
20
- * (local / staging / production baseUrls). Does not overwrite an existing file.
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 `envPresets` in daxta.config
109
- * (local / staging / production baseUrls). Does not overwrite an existing file.
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 variables = [{ key: 'baseUrl', value: String(preset.baseUrl || config.baseUrl) }];
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 === 'baseUrl')
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",
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": {