nest-graph-inspector 0.13.0 → 0.13.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,7 +4,10 @@ import { StringDecoder } from 'node:string_decoder';
4
4
  import { Injectable } from '@nestjs/common';
5
5
  import { createInspectorEndpointInfo } from '../inspector-endpoint-info';
6
6
  import { OutputAdapter } from '../ports/output.adapter';
7
- import { NestGraphInspectorOutput } from '../nest-graph-inspector.type';
7
+ import {
8
+ NestGraphInspectorLayoutOptions,
9
+ NestGraphInspectorOutput,
10
+ } from '../nest-graph-inspector.type';
8
11
  import type { GraphOutput } from '../types/graph-output.type';
9
12
  import type { GraphLayout } from '../types/graph-layout.type';
10
13
  import { GRAPH_OUTPUT_JSON_SCHEMA } from '../types/graph-output.schema';
@@ -19,8 +22,8 @@ import { AccessTokenService } from '../access-token.service';
19
22
 
20
23
  type HttpOutputConfig = Extract<NestGraphInspectorOutput, { type: 'http' }>;
21
24
 
22
- /** Used when neither the output nor the module sets `layoutFilePath`. */
23
- export const DEFAULT_LAYOUT_FILE_PATH = './nest-graph-layout.json';
25
+ /** Where the graph layout is saved when `ui.layout.saveAs` is `'file'`. */
26
+ export const DEFAULT_LAYOUT_FILE_PATH = './.muse';
24
27
 
25
28
  /**
26
29
  * Upper bound on a layout request body, in encoded bytes. A large
@@ -61,6 +64,9 @@ interface HttpOutputInternalOptions {
61
64
  * When provided, the adapter will reuse the given HttpServeAdapter instance instead of creating a new one. This is useful for scenarios where multiple outputs need to be served on the same HTTP server instance.
62
65
  */
63
66
  httpAdapter?: HttpServeAdapter;
67
+
68
+ /** How this output persists the graph layout. */
69
+ layout?: NestGraphInspectorLayoutOptions;
64
70
  }
65
71
 
66
72
  @Injectable()
@@ -75,6 +81,12 @@ export class HttpOutputAdapter implements OutputAdapter<HttpOutputConfig> {
75
81
  /** The layout write still running, or last queued, for each file. */
76
82
  private readonly pendingLayoutWrites = new Map<string, Promise<void>>();
77
83
 
84
+ /** The layout for every output whose `ui.layout.saveAs` is `'runtime'`. */
85
+ private inMemoryLayout: GraphLayout = {
86
+ version: GRAPH_LAYOUT_SCHEMA_VERSION,
87
+ modules: {},
88
+ };
89
+
78
90
  constructor(
79
91
  private readonly fileOutputAdapter: FileOutputAdapter,
80
92
  private readonly httpServeAdapter: HttpServeAdapter,
@@ -95,10 +107,8 @@ export class HttpOutputAdapter implements OutputAdapter<HttpOutputConfig> {
95
107
  this.joinPath(path, 'layout.json'),
96
108
  this.joinPath(path, 'layout'),
97
109
  ];
98
- const layoutFilePath = resolve(
99
- process.cwd(),
100
- config.layoutFilePath ?? DEFAULT_LAYOUT_FILE_PATH,
101
- );
110
+ const saveAs = config.layout?.saveAs ?? 'file';
111
+ const layoutFilePath = resolve(process.cwd(), DEFAULT_LAYOUT_FILE_PATH);
102
112
  const inspectorEndpointInfo = await createInspectorEndpointInfo(false);
103
113
 
104
114
  const isReuseHttpAdapter = !!config.httpAdapter;
@@ -146,7 +156,10 @@ export class HttpOutputAdapter implements OutputAdapter<HttpOutputConfig> {
146
156
  ...layoutOutputPaths.flatMap((layoutOutputPath) => [
147
157
  httpAdapter.get(
148
158
  layoutOutputPath,
149
- () => this.readLayout(layoutFilePath),
159
+ () =>
160
+ saveAs === 'runtime'
161
+ ? this.readLayoutFromMemory()
162
+ : this.readLayout(layoutFilePath),
150
163
  {
151
164
  responseHeaders: {
152
165
  'content-type': 'application/json; charset=utf-8',
@@ -155,7 +168,10 @@ export class HttpOutputAdapter implements OutputAdapter<HttpOutputConfig> {
155
168
  ),
156
169
  httpAdapter.post(
157
170
  layoutOutputPath,
158
- ({ request }) => this.saveLayout(request, layoutFilePath),
171
+ ({ request }) =>
172
+ saveAs === 'runtime'
173
+ ? this.saveLayoutToMemory(request)
174
+ : this.saveLayout(request, layoutFilePath),
159
175
  {
160
176
  responseHeaders: {
161
177
  'content-type': 'application/json; charset=utf-8',
@@ -272,43 +288,83 @@ export class HttpOutputAdapter implements OutputAdapter<HttpOutputConfig> {
272
288
  request: NodeJS.ReadableStream,
273
289
  filePath: string,
274
290
  ): Promise<HttpServeResponse> {
291
+ const parsed = await this.parseLayoutRequestBody(request);
292
+ if (!parsed.ok) {
293
+ return parsed.response;
294
+ }
295
+
296
+ try {
297
+ await this.writeLayout(filePath, parsed.layout);
298
+ } catch (err) {
299
+ return this.layoutFailure(
300
+ 500,
301
+ `Graph layout could not be saved to ${filePath}: ${errorMessage(err)}`,
302
+ );
303
+ }
304
+
305
+ return {
306
+ statusCode: 200,
307
+ body: { ok: true, message: 'Layout saved successfully' },
308
+ };
309
+ }
310
+
311
+ /** The in-memory layout for a `saveAs: 'runtime'` output. */
312
+ private readLayoutFromMemory(): HttpServeResponse {
313
+ return { statusCode: 200, body: this.inMemoryLayout };
314
+ }
315
+
316
+ private async saveLayoutToMemory(
317
+ request: NodeJS.ReadableStream,
318
+ ): Promise<HttpServeResponse> {
319
+ const parsed = await this.parseLayoutRequestBody(request);
320
+ if (!parsed.ok) {
321
+ return parsed.response;
322
+ }
323
+
324
+ this.inMemoryLayout = parsed.layout;
325
+
326
+ return {
327
+ statusCode: 200,
328
+ body: { ok: true, message: 'Layout saved successfully' },
329
+ };
330
+ }
331
+
332
+ private async parseLayoutRequestBody(
333
+ request: NodeJS.ReadableStream,
334
+ ): Promise<
335
+ { ok: true; layout: GraphLayout } | { ok: false; response: HttpServeResponse }
336
+ > {
275
337
  const bodyResult = await this.readLayoutBody(request);
276
338
  if (!bodyResult.ok) {
277
- return bodyResult.response;
339
+ return bodyResult;
278
340
  }
279
341
 
280
342
  let payload: unknown;
281
343
  try {
282
344
  payload = JSON.parse(bodyResult.text);
283
345
  } catch {
284
- return this.layoutFailure(400, 'Request body is not valid JSON.');
346
+ return {
347
+ ok: false,
348
+ response: this.layoutFailure(400, 'Request body is not valid JSON.'),
349
+ };
285
350
  }
286
351
 
287
352
  const validation = validateGraphLayout(payload);
288
353
  if (!validation.ok) {
289
354
  return {
290
- statusCode: 400,
291
- body: {
292
- ok: false,
293
- message: 'Invalid layout payload',
294
- errors: validation.errors,
355
+ ok: false,
356
+ response: {
357
+ statusCode: 400,
358
+ body: {
359
+ ok: false,
360
+ message: 'Invalid layout payload',
361
+ errors: validation.errors,
362
+ },
295
363
  },
296
364
  };
297
365
  }
298
366
 
299
- try {
300
- await this.writeLayout(filePath, validation.layout);
301
- } catch (err) {
302
- return this.layoutFailure(
303
- 500,
304
- `Graph layout could not be saved to ${filePath}: ${errorMessage(err)}`,
305
- );
306
- }
307
-
308
- return {
309
- statusCode: 200,
310
- body: { ok: true, message: 'Layout saved successfully' },
311
- };
367
+ return { ok: true, layout: validation.layout };
312
368
  }
313
369
 
314
370
  /**
@@ -175,18 +175,18 @@ describe(ViewerOutputAdapter.name, () => {
175
175
  );
176
176
  });
177
177
 
178
- it('passes its layout file path to the HTTP output adapter', async () => {
178
+ it('passes its layout options to the HTTP output adapter', async () => {
179
179
  await adapter.execute({} as never, {
180
180
  type: 'viewer',
181
181
  host: '127.0.0.1',
182
182
  port: 3998,
183
183
  path: 'graph',
184
- layoutFilePath: 'layouts/graph.json',
185
- });
184
+ layout: { saveAs: 'runtime' },
185
+ } as never);
186
186
 
187
187
  expect(httpOutputAdapter.execute).toHaveBeenCalledWith(
188
188
  {},
189
- expect.objectContaining({ layoutFilePath: 'layouts/graph.json' }),
189
+ expect.objectContaining({ layout: { saveAs: 'runtime' } }),
190
190
  );
191
191
  });
192
192
 
@@ -1,6 +1,9 @@
1
1
  import { Injectable } from '@nestjs/common';
2
2
  import { OutputAdapter } from '../ports/output.adapter';
3
- import { NestGraphInspectorOutput } from '../nest-graph-inspector.type';
3
+ import {
4
+ NestGraphInspectorLayoutOptions,
5
+ NestGraphInspectorOutput,
6
+ } from '../nest-graph-inspector.type';
4
7
  import { GraphOutputSource, HttpOutputAdapter } from './http-output.adapter';
5
8
  import { HttpServeAdapter } from './http-serve.adapter';
6
9
  import { DirectRunOutputAdapter } from './direct-run-output.adapter';
@@ -13,6 +16,7 @@ import { AccessTokenService } from '../access-token.service';
13
16
 
14
17
  type ViewerOutputConfig = Extract<NestGraphInspectorOutput, { type: 'viewer' }>;
15
18
  type ViewerOutputInternalConfig = ViewerOutputConfig & {
19
+ layout?: NestGraphInspectorLayoutOptions;
16
20
  directRun?: {
17
21
  enabled?: boolean;
18
22
  path: string;
@@ -68,7 +72,7 @@ export class ViewerOutputAdapter implements OutputAdapter<ViewerOutputConfig> {
68
72
  host: config.host,
69
73
  port: config.port,
70
74
  path,
71
- layoutFilePath: config.layoutFilePath,
75
+ layout: internalConfig.layout,
72
76
  httpAdapter: this.httpServeAdapter,
73
77
  });
74
78
 
@@ -345,7 +345,7 @@ describe(NestGraphInspectorSetup.name, () => {
345
345
  type: "viewer",
346
346
  host: "127.0.0.1",
347
347
  port: 3998,
348
- layoutFilePath: "./nest-graph-layout.json",
348
+ layout: undefined,
349
349
  directRun: {
350
350
  enabled: true,
351
351
  path: "/direct-run",
@@ -379,7 +379,7 @@ describe(NestGraphInspectorSetup.name, () => {
379
379
  type: "viewer",
380
380
  host: "127.0.0.1",
381
381
  port: 3998,
382
- layoutFilePath: "./nest-graph-layout.json",
382
+ layout: undefined,
383
383
  directRun: {
384
384
  enabled: true,
385
385
  path: "/run",
@@ -407,7 +407,7 @@ describe(NestGraphInspectorSetup.name, () => {
407
407
  type: "viewer",
408
408
  host: "127.0.0.1",
409
409
  port: 3998,
410
- layoutFilePath: "./nest-graph-layout.json",
410
+ layout: undefined,
411
411
  directRun: {
412
412
  enabled: true,
413
413
  path: "/direct-run",
@@ -442,7 +442,7 @@ describe(NestGraphInspectorSetup.name, () => {
442
442
  type: "viewer",
443
443
  host: "127.0.0.1",
444
444
  port: 3998,
445
- layoutFilePath: "./nest-graph-layout.json",
445
+ layout: undefined,
446
446
  directRun: {
447
447
  enabled: true,
448
448
  path: "/direct-run",
@@ -458,7 +458,7 @@ describe(NestGraphInspectorSetup.name, () => {
458
458
  );
459
459
  });
460
460
 
461
- it("should give an http output the default layout file path", async () => {
461
+ it("should not set a layout option on an http output when none is configured", async () => {
462
462
  options.outputs = [{ type: "http", host: "127.0.0.1", port: 3998 }];
463
463
 
464
464
  await service.onModuleInit();
@@ -469,13 +469,13 @@ describe(NestGraphInspectorSetup.name, () => {
469
469
  type: "http",
470
470
  host: "127.0.0.1",
471
471
  port: 3998,
472
- layoutFilePath: "./nest-graph-layout.json",
472
+ layout: undefined,
473
473
  },
474
474
  );
475
475
  });
476
476
 
477
- it("should let a module-level layoutFilePath apply to every viewer and http output", async () => {
478
- options.layoutFilePath = "layouts/graph.json";
477
+ it("should let a module-level ui.layout apply to every viewer and http output", async () => {
478
+ options.ui = { layout: { saveAs: "runtime" } };
479
479
  options.outputs = [
480
480
  { type: "viewer", host: "127.0.0.1", port: 3998 },
481
481
  { type: "http", host: "127.0.0.1", port: 3999 },
@@ -485,45 +485,16 @@ describe(NestGraphInspectorSetup.name, () => {
485
485
 
486
486
  expect(viewerOutputAdapter.execute).toHaveBeenCalledWith(
487
487
  expect.any(Function),
488
- expect.objectContaining({ layoutFilePath: "layouts/graph.json" }),
488
+ expect.objectContaining({ layout: { saveAs: "runtime" } }),
489
489
  );
490
490
  expect(httpOutputAdapter.execute).toHaveBeenCalledWith(
491
491
  expect.anything(),
492
- expect.objectContaining({ layoutFilePath: "layouts/graph.json" }),
492
+ expect.objectContaining({ layout: { saveAs: "runtime" } }),
493
493
  );
494
494
  });
495
495
 
496
- it("should let an output's own layoutFilePath override the module-level one", async () => {
497
- options.layoutFilePath = "layouts/graph.json";
498
- options.outputs = [
499
- {
500
- type: "viewer",
501
- host: "127.0.0.1",
502
- port: 3998,
503
- layoutFilePath: "viewer-layout.json",
504
- },
505
- {
506
- type: "http",
507
- host: "127.0.0.1",
508
- port: 3999,
509
- layoutFilePath: "http-layout.json",
510
- },
511
- ];
512
-
513
- await service.onModuleInit();
514
-
515
- expect(viewerOutputAdapter.execute).toHaveBeenCalledWith(
516
- expect.any(Function),
517
- expect.objectContaining({ layoutFilePath: "viewer-layout.json" }),
518
- );
519
- expect(httpOutputAdapter.execute).toHaveBeenCalledWith(
520
- expect.anything(),
521
- expect.objectContaining({ layoutFilePath: "http-layout.json" }),
522
- );
523
- });
524
-
525
- it("should not give file outputs a layout file path", async () => {
526
- options.layoutFilePath = "layouts/graph.json";
496
+ it("should not give file outputs a layout option", async () => {
497
+ options.ui = { layout: { saveAs: "runtime" } };
527
498
  options.outputs = [
528
499
  { type: "json", path: "graph.json" },
529
500
  { type: "markdown", path: "graph.md" },
@@ -14,6 +14,7 @@ import { DiscoveryAdapter } from "./adapters/discovery";
14
14
  import type { AnyFunction, ModuleTree } from "./adapters/discovery";
15
15
  import { MODULE_OPTIONS_TOKEN } from "./nest-graph-inspector.config";
16
16
  import type {
17
+ NestGraphInspectorLayoutOptions,
17
18
  NestGraphInspectorModuleOptions,
18
19
  NestGraphInspectorOutput,
19
20
  } from "./nest-graph-inspector.type";
@@ -38,10 +39,7 @@ import type {
38
39
  GraphOutputProviderCycle,
39
40
  GraphOutputProviderCyclePathItem,
40
41
  } from "./types/graph-output.type";
41
- import {
42
- DEFAULT_LAYOUT_FILE_PATH,
43
- HttpOutputAdapter,
44
- } from "./adapters/http-output.adapter";
42
+ import { HttpOutputAdapter } from "./adapters/http-output.adapter";
45
43
  import { FileOutputAdapter } from "./adapters/file-output.adapter";
46
44
  import { JsonOutputAdapter } from "./adapters/json-output.adapter";
47
45
  import { ViewerOutputAdapter } from "./adapters/viewer-output.adapter";
@@ -218,31 +216,26 @@ export class NestGraphInspectorSetup implements OnModuleInit {
218
216
 
219
217
  private withDefaultOutputOptions(
220
218
  output: NestGraphInspectorOutput,
221
- ): NestGraphInspectorOutput {
219
+ ): NestGraphInspectorOutput & { layout?: NestGraphInspectorLayoutOptions } {
222
220
  if (output.type !== "viewer" && output.type !== "http") {
223
221
  return output;
224
222
  }
225
223
 
226
- // Precedence, most specific first: the output's own `layoutFilePath`,
227
- // then the module-wide one, then the built-in default.
228
- const layoutFilePath =
229
- output.layoutFilePath ??
230
- this.options.layoutFilePath ??
231
- DEFAULT_LAYOUT_FILE_PATH;
224
+ const layout = this.options.ui?.layout;
232
225
  if (output.type === "http") {
233
- return { ...output, layoutFilePath };
226
+ return { ...output, layout };
234
227
  }
235
228
 
236
229
  const defaultViewerOutput = defaultOptions.outputs?.find(
237
230
  (defaultOutput) => defaultOutput.type === "viewer",
238
231
  );
239
232
  if (!defaultViewerOutput || defaultViewerOutput.type !== "viewer") {
240
- return { ...output, layoutFilePath };
233
+ return { ...output, layout };
241
234
  }
242
235
 
243
236
  return {
244
237
  ...output,
245
- layoutFilePath,
238
+ layout,
246
239
  directRun: this.mergeViewerDirectRunOptions(
247
240
  defaultViewerOutput.directRun,
248
241
  output.directRun,
@@ -142,11 +142,6 @@ export type NestGraphInspectorOutput =
142
142
  port?: number;
143
143
  path?: string;
144
144
  directRun?: NestGraphInspectorViewerDirectRunOptions;
145
- /**
146
- * Where this output reads and saves the graph layout. Overrides the
147
- * module-wide `layoutFilePath`.
148
- */
149
- layoutFilePath?: string;
150
145
  }
151
146
  | { type: 'markdown'; path: string }
152
147
  | { type: 'json'; path: string }
@@ -156,11 +151,6 @@ export type NestGraphInspectorOutput =
156
151
  host?: string;
157
152
  port?: number;
158
153
  path?: string;
159
- /**
160
- * Where this output reads and saves the graph layout. Overrides the
161
- * module-wide `layoutFilePath`.
162
- */
163
- layoutFilePath?: string;
164
154
  };
165
155
 
166
156
  export type NestGraphInspectorViewerOptions = Extract<
@@ -168,6 +158,19 @@ export type NestGraphInspectorViewerOptions = Extract<
168
158
  { type: 'viewer' }
169
159
  >;
170
160
 
161
+ export interface NestGraphInspectorLayoutOptions {
162
+ /**
163
+ * How graph layout is persisted.
164
+ * - 'file' (default): saved to ./.muse relative to process.cwd()
165
+ * - 'runtime': stored purely in RAM; resets on app restart
166
+ */
167
+ saveAs?: 'file' | 'runtime';
168
+ }
169
+
170
+ export interface NestGraphInspectorUiOptions {
171
+ layout?: NestGraphInspectorLayoutOptions;
172
+ }
173
+
171
174
  export interface NestGraphInspectorModuleOptions {
172
175
  /**
173
176
  * Which "Root" of module that need to be inspect
@@ -242,12 +245,9 @@ export interface NestGraphInspectorModuleOptions {
242
245
  directRun?: NestGraphInspectorViewerDirectRunOptions;
243
246
 
244
247
  /**
245
- * The file the viewer's graph layout is read from (`GET {path}/layout.json`)
246
- * and saved to (`POST {path}/layout`), for every `viewer` and `http` output
247
- * that does not set its own `layoutFilePath`.
248
- *
249
- * Defaults to `'./nest-graph-layout.json'`. A relative path resolves against
250
- * `process.cwd()`; missing parent directories are created on save.
248
+ * UI-facing settings for the viewer, applied to every `viewer` and `http`
249
+ * output. Layout persistence is a module-wide setting with no per-output
250
+ * override.
251
251
  */
252
- layoutFilePath?: string;
252
+ ui?: NestGraphInspectorUiOptions;
253
253
  }
@@ -23,8 +23,10 @@ export type GraphLayoutModule = {
23
23
  };
24
24
 
25
25
  /**
26
- * The arrangement of a graph in the viewer, persisted to `layoutFilePath` and
27
- * served at `{path}/layout.json`.
26
+ * The arrangement of a graph in the viewer, served at `{path}/layout.json`.
27
+ * Persisted according to `ui.layout.saveAs`: `'file'` (default) saves to
28
+ * `./.muse` relative to `process.cwd()`; `'runtime'` keeps it in memory only,
29
+ * resetting on restart.
28
30
  */
29
31
  export type GraphLayout = {
30
32
  $schema?: string;