@graphql-markdown/printer-legacy 1.14.0 → 1.15.0

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.
Files changed (49) hide show
  1. package/dist/const/options.d.ts +15 -2
  2. package/dist/const/options.d.ts.map +1 -1
  3. package/dist/const/options.js +19 -6
  4. package/dist/directive.d.ts +3 -3
  5. package/dist/directive.d.ts.map +1 -1
  6. package/dist/directive.js +8 -4
  7. package/dist/events.d.ts +77 -0
  8. package/dist/events.d.ts.map +1 -0
  9. package/dist/events.js +85 -0
  10. package/dist/example.d.ts.map +1 -1
  11. package/dist/example.js +12 -7
  12. package/dist/format-helpers.d.ts +9 -0
  13. package/dist/format-helpers.d.ts.map +1 -1
  14. package/dist/format-helpers.js +10 -1
  15. package/dist/formatter.js +1 -1
  16. package/dist/graphql/directive.d.ts +3 -3
  17. package/dist/graphql/directive.d.ts.map +1 -1
  18. package/dist/graphql/directive.js +3 -3
  19. package/dist/graphql/enum.d.ts +3 -3
  20. package/dist/graphql/enum.d.ts.map +1 -1
  21. package/dist/graphql/enum.js +2 -2
  22. package/dist/graphql/object.d.ts +3 -3
  23. package/dist/graphql/object.d.ts.map +1 -1
  24. package/dist/graphql/object.js +4 -4
  25. package/dist/graphql/operation.d.ts +6 -7
  26. package/dist/graphql/operation.d.ts.map +1 -1
  27. package/dist/graphql/operation.js +41 -8
  28. package/dist/graphql/scalar.d.ts +5 -5
  29. package/dist/graphql/scalar.d.ts.map +1 -1
  30. package/dist/graphql/scalar.js +7 -7
  31. package/dist/graphql/union.d.ts +3 -3
  32. package/dist/graphql/union.d.ts.map +1 -1
  33. package/dist/graphql/union.js +2 -2
  34. package/dist/group.d.ts.map +1 -1
  35. package/dist/group.js +7 -6
  36. package/dist/index.d.ts +2 -0
  37. package/dist/index.d.ts.map +1 -1
  38. package/dist/index.js +5 -1
  39. package/dist/link.d.ts +1 -1
  40. package/dist/link.d.ts.map +1 -1
  41. package/dist/link.js +7 -6
  42. package/dist/mdx/index.js +2 -2
  43. package/dist/printer.d.ts +65 -21
  44. package/dist/printer.d.ts.map +1 -1
  45. package/dist/printer.js +268 -117
  46. package/dist/section.d.ts +3 -3
  47. package/dist/section.d.ts.map +1 -1
  48. package/dist/section.js +26 -11
  49. package/package.json +17 -6
package/dist/printer.js CHANGED
@@ -20,7 +20,22 @@ const PrintTypeEvents = {
20
20
  AFTER_PRINT_CODE: "print:afterPrintCode",
21
21
  BEFORE_PRINT_TYPE: "print:beforePrintType",
22
22
  AFTER_PRINT_TYPE: "print:afterPrintType",
23
+ BEFORE_COMPOSE_PAGE_TYPE: "print:beforeComposePageType",
23
24
  };
25
+ const TYPE_PAGE_HEADER_ORDER = [
26
+ "header",
27
+ "metatags",
28
+ "mdxDeclaration",
29
+ ];
30
+ const TYPE_PAGE_SECTION_ORDER = [
31
+ "tags",
32
+ "description",
33
+ "code",
34
+ "customDirectives",
35
+ "metadata",
36
+ "example",
37
+ "relations",
38
+ ];
24
39
  const graphql_1 = require("@graphql-markdown/graphql");
25
40
  const utils_1 = require("@graphql-markdown/utils");
26
41
  const relation_1 = require("./relation");
@@ -33,6 +48,7 @@ const strings_1 = require("./const/strings");
33
48
  const formatter_1 = require("./formatter");
34
49
  const options_1 = require("./const/options");
35
50
  const example_1 = require("./example");
51
+ const events_1 = require("./events");
36
52
  /**
37
53
  * Default initialization options for the Printer class.
38
54
  * @internal
@@ -61,16 +77,6 @@ const DEFAULT_INIT_OPTIONS = {
61
77
  * ```
62
78
  */
63
79
  class Printer {
64
- /**
65
- * Global printer configuration options
66
- */
67
- static options;
68
- /**
69
- * Optional event emitter for print events.
70
- * When set, the printer will emit events before/after printCode and printType,
71
- * allowing external code to intercept and modify the output.
72
- */
73
- static eventEmitter;
74
80
  /**
75
81
  * Prints type descriptions
76
82
  */
@@ -83,10 +89,47 @@ class Printer {
83
89
  * Prints custom tags
84
90
  */
85
91
  static printCustomTags = directive_1.printCustomTags;
92
+ static _eventEmitter;
93
+ static _options;
94
+ static _deprecatedOptions;
95
+ static _mdxDeclaration;
96
+ /**
97
+ * Global printer configuration options
98
+ */
99
+ static get options() {
100
+ return Printer._options;
101
+ }
102
+ /**
103
+ * Backward-compat section toggles extracted from legacy config options.
104
+ *
105
+ * These flags are applied only during section order composition.
106
+ */
107
+ static get deprecatedOptions() {
108
+ return Printer._deprecatedOptions;
109
+ }
110
+ /**
111
+ * Optional event emitter for print events.
112
+ * When set, the printer will emit events before/after printCode and printType,
113
+ * allowing external code to intercept and modify the output.
114
+ */
115
+ static get eventEmitter() {
116
+ return Printer._eventEmitter;
117
+ }
86
118
  /**
87
119
  * Prints mdx modules import declaration
88
120
  */
89
- static mdxDeclaration;
121
+ static get mdxDeclaration() {
122
+ return Printer._mdxDeclaration;
123
+ }
124
+ static set options(options) {
125
+ Printer._options = options;
126
+ }
127
+ static set eventEmitter(eventEmitter) {
128
+ Printer._eventEmitter = eventEmitter;
129
+ }
130
+ static set mdxDeclaration(mdxDeclaration) {
131
+ Printer._mdxDeclaration = mdxDeclaration;
132
+ }
90
133
  /**
91
134
  * Initializes the printer with the given schema and configuration.
92
135
  *
@@ -101,35 +144,51 @@ class Printer {
101
144
  static async init(schema, baseURL = "schema", linkRoot = "/", { customDirectives, groups, meta, metatags, onlyDocDirectives, printTypeOptions, skipDocDirectives, sectionHeaderId, } = DEFAULT_INIT_OPTIONS, formatter, mdxDeclaration, eventEmitter) {
102
145
  // Always update eventEmitter regardless of initialization state
103
146
  Printer.eventEmitter = eventEmitter ?? null;
104
- if (Printer.options !== undefined) {
105
- return;
147
+ if (Printer.options === undefined) {
148
+ Printer.options = {
149
+ ...options_1.DEFAULT_OPTIONS,
150
+ basePath: utils_1.pathUrl.join(linkRoot ?? "", baseURL ?? ""),
151
+ customDirectives,
152
+ exampleSection: typeof printTypeOptions?.exampleSection === "object"
153
+ ? printTypeOptions.exampleSection
154
+ : undefined,
155
+ groups,
156
+ parentTypePrefix: printTypeOptions?.parentTypePrefix ??
157
+ options_1.PRINT_TYPE_DEFAULT_OPTIONS.parentTypePrefix,
158
+ deprecated: printTypeOptions?.deprecated ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.deprecated,
159
+ schema,
160
+ onlyDocDirectives: onlyDocDirectives ?? [],
161
+ skipDocDirectives: skipDocDirectives ?? [],
162
+ sectionHeaderId: sectionHeaderId ?? options_1.DEFAULT_OPTIONS.sectionHeaderId,
163
+ typeBadges: printTypeOptions?.typeBadges ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.typeBadges,
164
+ metatags: metatags ?? [],
165
+ hierarchy: printTypeOptions?.hierarchy ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.hierarchy,
166
+ meta: meta,
167
+ // Merge formatter functions: default formatter with any overrides
168
+ ...(0, formatter_1.createDefaultFormatter)(),
169
+ ...formatter,
170
+ };
171
+ const initExampleSection = printTypeOptions?.exampleSection;
172
+ let deprecatedExampleSection;
173
+ if (typeof initExampleSection === "boolean") {
174
+ deprecatedExampleSection = initExampleSection;
175
+ }
176
+ else if (initExampleSection === undefined) {
177
+ deprecatedExampleSection =
178
+ options_1.PRINT_TYPE_DEFAULT_DEPRECATED_OPTIONS.exampleSection;
179
+ }
180
+ else {
181
+ deprecatedExampleSection = true;
182
+ }
183
+ Printer._deprecatedOptions = {
184
+ codeSection: printTypeOptions?.codeSection ??
185
+ options_1.PRINT_TYPE_DEFAULT_DEPRECATED_OPTIONS.codeSection,
186
+ exampleSection: deprecatedExampleSection,
187
+ relatedTypeSection: printTypeOptions?.relatedTypeSection ??
188
+ options_1.PRINT_TYPE_DEFAULT_DEPRECATED_OPTIONS.relatedTypeSection,
189
+ };
190
+ Printer.mdxDeclaration = mdxDeclaration ?? "";
106
191
  }
107
- Printer.options = {
108
- ...options_1.DEFAULT_OPTIONS,
109
- basePath: utils_1.pathUrl.join(linkRoot ?? "", baseURL ?? ""),
110
- codeSection: printTypeOptions?.codeSection ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.codeSection,
111
- customDirectives,
112
- exampleSection: printTypeOptions?.exampleSection ??
113
- options_1.PRINT_TYPE_DEFAULT_OPTIONS.exampleSection,
114
- groups,
115
- parentTypePrefix: printTypeOptions?.parentTypePrefix ??
116
- options_1.PRINT_TYPE_DEFAULT_OPTIONS.parentTypePrefix,
117
- deprecated: printTypeOptions?.deprecated ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.deprecated,
118
- relatedTypeSection: printTypeOptions?.relatedTypeSection ??
119
- options_1.PRINT_TYPE_DEFAULT_OPTIONS.relatedTypeSection,
120
- schema,
121
- onlyDocDirectives: onlyDocDirectives ?? [],
122
- skipDocDirectives: skipDocDirectives ?? [],
123
- sectionHeaderId: sectionHeaderId ?? options_1.DEFAULT_OPTIONS.sectionHeaderId,
124
- typeBadges: printTypeOptions?.typeBadges ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.typeBadges,
125
- metatags: metatags ?? [],
126
- hierarchy: printTypeOptions?.hierarchy ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.hierarchy,
127
- meta: meta,
128
- // Merge formatter functions: default formatter with any overrides
129
- ...(0, formatter_1.createDefaultFormatter)(),
130
- ...formatter,
131
- };
132
- Printer.mdxDeclaration = mdxDeclaration ?? "";
133
192
  }
134
193
  /**
135
194
  * Prints the header section of a type documentation
@@ -154,9 +213,6 @@ class Printer {
154
213
  * @returns Formatted code block string with type definition
155
214
  */
156
215
  static printCode = (type, options) => {
157
- if (options.codeSection === undefined || options.codeSection !== true) {
158
- return "";
159
- }
160
216
  let code = "";
161
217
  switch (true) {
162
218
  case (0, graphql_1.isOperation)(type):
@@ -214,14 +270,7 @@ class Printer {
214
270
  // Create mutable event data - handlers can modify options
215
271
  const eventData = { type, typeName, options: { ...options } };
216
272
  // Emit BEFORE event - handlers can modify inputs or prevent default
217
- const beforeEvent = {
218
- data: eventData,
219
- output: "",
220
- defaultPrevented: false,
221
- preventDefault() {
222
- this.defaultPrevented = true;
223
- },
224
- };
273
+ const beforeEvent = new events_1.PrintCodeEvent(eventData, "");
225
274
  await Printer.eventEmitter.emitAsync(PrintTypeEvents.BEFORE_PRINT_CODE, beforeEvent);
226
275
  // If prevented, handlers should have set the output they want
227
276
  if (beforeEvent.defaultPrevented) {
@@ -230,10 +279,7 @@ class Printer {
230
279
  // Generate code using the (potentially modified) options from event data
231
280
  const output = Printer.printCode(type, eventData.options);
232
281
  // Emit AFTER event - handlers can modify the output
233
- const afterEvent = {
234
- data: eventData,
235
- output,
236
- };
282
+ const afterEvent = new events_1.PrintCodeEvent(eventData, output);
237
283
  await Printer.eventEmitter.emitAsync(PrintTypeEvents.AFTER_PRINT_CODE, afterEvent);
238
284
  return afterEvent.output;
239
285
  };
@@ -242,27 +288,24 @@ class Printer {
242
288
  *
243
289
  * @param type - GraphQL type to generate example for
244
290
  * @param options - Printer configuration options
245
- * @returns Formatted example section string or empty string if no example
291
+ * @returns Example page section or undefined when no example is available
246
292
  */
247
293
  static printExample = (type, options) => {
248
- if (options.exampleSection === undefined ||
249
- options.exampleSection === null ||
250
- options.exampleSection === false) {
251
- return "";
252
- }
253
294
  const example = (0, example_1.printExample)(type, options);
254
295
  if (!example) {
255
- return "";
296
+ return undefined;
256
297
  }
257
- return `${options_1.SectionLevels.LEVEL.repeat(3)} Example${strings_1.MARKDOWN_EOP}${strings_1.MARKDOWN_SOC}${example}${strings_1.MARKDOWN_EOC}${strings_1.MARKDOWN_EOP}`;
298
+ return {
299
+ content: `${strings_1.MARKDOWN_SOC}${example}${strings_1.MARKDOWN_EOC}${strings_1.MARKDOWN_EOP}`,
300
+ title: "Example",
301
+ };
258
302
  };
259
303
  /**
260
304
  * Prints metadata information for a GraphQL type
261
305
  *
262
306
  * @param type - GraphQL type to print metadata for
263
307
  * @param options - Printer configuration options
264
- * @returns Formatted metadata string as MDX or plain string
265
- * @throws When type is not supported
308
+ * @returns Metadata section (or section list) for supported types, otherwise undefined
266
309
  */
267
310
  static printTypeMetadata = (type, options) => {
268
311
  switch (true) {
@@ -283,7 +326,7 @@ class Printer {
283
326
  case (0, graphql_1.isOperation)(type):
284
327
  return (0, graphql_2.printOperationMetadata)(type, options);
285
328
  default:
286
- return "";
329
+ return undefined;
287
330
  }
288
331
  };
289
332
  /**
@@ -294,9 +337,6 @@ class Printer {
294
337
  * @returns Formatted relations section as MDX or plain string
295
338
  */
296
339
  static printRelations = (type, options) => {
297
- if (options.relatedTypeSection !== true) {
298
- return "";
299
- }
300
340
  return (0, relation_1.printRelations)(type, options);
301
341
  };
302
342
  /**
@@ -329,8 +369,7 @@ class Printer {
329
369
  * @example
330
370
  * ```typescript
331
371
  * const doc = await Printer.printType('User', UserType, {
332
- * frontMatter: true,
333
- * codeSection: true
372
+ * frontMatter: true
334
373
  * });
335
374
  * ```
336
375
  *
@@ -347,6 +386,7 @@ class Printer {
347
386
  *
348
387
  * When an event emitter is configured, emits events:
349
388
  * - `print:beforePrintType` - Before generating documentation
389
+ * - `print:beforeComposePageType` - Before composing section order and final page output
350
390
  * - `print:afterPrintType` - After generating documentation (output can be modified)
351
391
  */
352
392
  static printType = async (name, type, options) => {
@@ -355,6 +395,12 @@ class Printer {
355
395
  ...Printer.options,
356
396
  ...options,
357
397
  };
398
+ const deprecatedOptions = {
399
+ ...Printer.deprecatedOptions,
400
+ exampleSection: printTypeOptions.exampleSection
401
+ ? true
402
+ : Printer.deprecatedOptions?.exampleSection,
403
+ };
358
404
  if (!name || !(0, link_1.hasPrintableDirective)(type, printTypeOptions)) {
359
405
  return undefined;
360
406
  }
@@ -362,21 +408,7 @@ class Printer {
362
408
  const eventData = { type, name, options: printTypeOptions };
363
409
  // Emit BEFORE_PRINT_TYPE event if emitter is configured
364
410
  if (Printer.eventEmitter) {
365
- const beforeEvent = {
366
- data: eventData,
367
- output: undefined,
368
- defaultPrevented: false,
369
- propagationStopped: false,
370
- preventDefault() {
371
- this.defaultPrevented = true;
372
- },
373
- stopPropagation() {
374
- this.propagationStopped = true;
375
- },
376
- async runDefaultAction() {
377
- return void 0;
378
- },
379
- };
411
+ const beforeEvent = new events_1.PrintTypeEvent(eventData, undefined);
380
412
  await Printer.eventEmitter.emitAsync(PrintTypeEvents.BEFORE_PRINT_TYPE, beforeEvent);
381
413
  // If prevented, return the output set by handlers (or undefined)
382
414
  if (beforeEvent.defaultPrevented) {
@@ -386,50 +418,169 @@ class Printer {
386
418
  const header = Printer.printHeader(name, (0, graphql_1.getTypeName)(type), printTypeOptions);
387
419
  const metatags = Printer.printMetaTags(type, printTypeOptions);
388
420
  const description = Printer.printDescription(type, printTypeOptions);
389
- // Use async code printing when event emitter is configured
390
- const code = Printer.eventEmitter
391
- ? await Printer.printCodeAsync(type, name, printTypeOptions)
392
- : Printer.printCode(type, printTypeOptions);
421
+ // Generate all sections unconditionally to support event hooks that might re-add
422
+ // sections excluded by deprecated toggles. This is a performance trade-off:
423
+ // sections excluded by deprecated flags (codeSection, exampleSection, relatedTypeSection)
424
+ // are still generated and print events emitted, even if they won't be rendered.
425
+ // TODO(perf): Implement lazy section generation based on final composed order
426
+ // when no BEFORE_COMPOSE_PAGE_TYPE listeners are registered.
427
+ const code = await Printer.printCodeAsync(type, name, printTypeOptions);
393
428
  const customDirectives = Printer.printCustomDirectives(type, printTypeOptions);
394
429
  const tags = Printer.printCustomTags(type, printTypeOptions);
395
430
  const metadata = Printer.printTypeMetadata(type, printTypeOptions);
396
431
  const relations = Printer.printRelations(type, printTypeOptions);
397
432
  const example = Printer.printExample(type, printTypeOptions);
398
- let output = [
399
- header,
400
- metatags,
401
- Printer.mdxDeclaration,
402
- tags,
403
- description,
404
- code,
405
- customDirectives,
406
- metadata,
407
- example,
408
- relations,
409
- ]
433
+ // Create sections map for composition events
434
+ const sections = {
435
+ header: { content: header },
436
+ metatags: { content: metatags },
437
+ mdxDeclaration: { content: Printer.mdxDeclaration ?? "" },
438
+ tags: Printer.normalizePageSection(tags),
439
+ description: Printer.normalizePageSection(description),
440
+ code: Printer.normalizePageSection(code),
441
+ customDirectives: Printer.normalizePageSection(customDirectives),
442
+ metadata: Printer.normalizePageSection(metadata),
443
+ example: Printer.normalizePageSection(example),
444
+ relations: Printer.normalizePageSection(relations),
445
+ };
446
+ let sectionOrder = Printer.getDeprecatedTypePageSectionOrder([...TYPE_PAGE_SECTION_ORDER], deprecatedOptions);
447
+ // Emit BEFORE_COMPOSE_PAGE_TYPE event if emitter is configured
448
+ if (Printer.eventEmitter) {
449
+ const beforeComposeEvent = new events_1.BeforeComposePageTypeEvent({ type, name, options: printTypeOptions, sections }, sectionOrder);
450
+ await Printer.eventEmitter.emitAsync(PrintTypeEvents.BEFORE_COMPOSE_PAGE_TYPE, beforeComposeEvent);
451
+ sectionOrder = Printer.sanitizeTypePageSectionOrder(beforeComposeEvent.output, sections);
452
+ }
453
+ // Compose output based on section order
454
+ const pageSections = [
455
+ ...TYPE_PAGE_HEADER_ORDER,
456
+ ...sectionOrder,
457
+ ];
458
+ let output = pageSections
459
+ .map((key) => {
460
+ return Printer.renderPageSection(sections[key]);
461
+ })
462
+ .filter((section) => {
463
+ return section.length > 0;
464
+ })
410
465
  .join(strings_1.MARKDOWN_EOP)
411
466
  .trim();
412
467
  // Emit AFTER_PRINT_TYPE event if emitter is configured
413
468
  if (Printer.eventEmitter) {
414
- const afterEvent = {
415
- data: eventData,
416
- output,
417
- defaultPrevented: false,
418
- propagationStopped: false,
419
- preventDefault() {
420
- this.defaultPrevented = true;
421
- },
422
- stopPropagation() {
423
- this.propagationStopped = true;
424
- },
425
- async runDefaultAction() {
426
- return void 0;
427
- },
428
- };
469
+ const afterEvent = new events_1.PrintTypeEvent(eventData, output);
429
470
  await Printer.eventEmitter.emitAsync(PrintTypeEvents.AFTER_PRINT_TYPE, afterEvent);
430
- output = afterEvent.output;
471
+ output = afterEvent.output ?? output;
431
472
  }
432
473
  return output;
433
474
  };
475
+ /**
476
+ * Renders a page section, optionally prefixing a heading when a title is present.
477
+ */
478
+ static renderPageSection = (section) => {
479
+ if (!section ||
480
+ typeof section !== "object" ||
481
+ Array.isArray(section) ||
482
+ (!("content" in section) && !("title" in section))) {
483
+ return "";
484
+ }
485
+ let content;
486
+ if (!("content" in section) || !section.content) {
487
+ content = "";
488
+ }
489
+ else if (Array.isArray(section.content)) {
490
+ content = section.content
491
+ .map((entry) => {
492
+ return Printer.renderPageSection(entry);
493
+ })
494
+ .filter((entry) => {
495
+ return entry.length > 0;
496
+ })
497
+ .join(strings_1.MARKDOWN_EOP);
498
+ }
499
+ else if (typeof section.content === "string") {
500
+ content = section.content;
501
+ }
502
+ else {
503
+ content = Printer.renderPageSection(section.content);
504
+ }
505
+ if (!("title" in section) || typeof section.title !== "string") {
506
+ if (!content || content.trim().length === 0) {
507
+ return "";
508
+ }
509
+ return content;
510
+ }
511
+ if (!section.title || section.title.trim().length === 0) {
512
+ if (!content || content.trim().length === 0) {
513
+ return "";
514
+ }
515
+ return content;
516
+ }
517
+ const level = Math.max(1, section.level ?? 3);
518
+ const title = `${options_1.SectionLevels.LEVEL.repeat(level)} ${section.title}${strings_1.MARKDOWN_EOP}`;
519
+ if (!content || content.trim().length === 0) {
520
+ return title;
521
+ }
522
+ return `${title}${content}`;
523
+ };
524
+ /**
525
+ * Returns the default content section order for type pages.
526
+ *
527
+ * Applies backward-compatibility toggles from deprecated section flags.
528
+ */
529
+ static getDeprecatedTypePageSectionOrder = (sections, deprecatedOptions) => {
530
+ return sections.filter((section) => {
531
+ if (section === "code") {
532
+ return deprecatedOptions.codeSection !== false;
533
+ }
534
+ if (section === "example") {
535
+ return deprecatedOptions.exampleSection !== false;
536
+ }
537
+ if (section === "relations") {
538
+ return deprecatedOptions.relatedTypeSection !== false;
539
+ }
540
+ return true;
541
+ });
542
+ };
543
+ /**
544
+ * Runtime guard for built-in page content section keys.
545
+ */
546
+ static isTypePageContentSection = (section) => {
547
+ return (typeof section === "string" &&
548
+ TYPE_PAGE_SECTION_ORDER.includes(section));
549
+ };
550
+ /**
551
+ * Runtime guard for header-only page section keys.
552
+ */
553
+ static isTypePageHeaderSection = (section) => {
554
+ return (typeof section === "string" &&
555
+ TYPE_PAGE_HEADER_ORDER.includes(section));
556
+ };
557
+ /**
558
+ * Normalizes event-driven section order, allowing built-in section keys and
559
+ * any custom keys that were added to the sections map by an event handler.
560
+ * Keys that are neither built-in nor present in the sections map are dropped.
561
+ */
562
+ static sanitizeTypePageSectionOrder = (sectionOrder, sections) => {
563
+ if (!Array.isArray(sectionOrder)) {
564
+ return [];
565
+ }
566
+ return sectionOrder.filter((section) => {
567
+ return (typeof section === "string" &&
568
+ !Printer.isTypePageHeaderSection(section) &&
569
+ (Printer.isTypePageContentSection(section) ||
570
+ Object.hasOwn(sections, section)));
571
+ });
572
+ };
573
+ /**
574
+ * Normalizes mixed section value shapes to the internal PageSection format.
575
+ */
576
+ static normalizePageSection = (section) => {
577
+ if (!section) {
578
+ return undefined;
579
+ }
580
+ if (typeof section === "string" || Array.isArray(section)) {
581
+ return { content: section };
582
+ }
583
+ return section;
584
+ };
434
585
  }
435
586
  exports.Printer = Printer;
package/dist/section.d.ts CHANGED
@@ -3,7 +3,7 @@
3
3
  * Handles the printing of section items, metadata, and structured documentation content.
4
4
  * @module section
5
5
  */
6
- import type { MDXString, PrintTypeOptions } from "@graphql-markdown/types";
6
+ import type { Maybe, MDXString, PageSection, PrintTypeOptions } from "@graphql-markdown/types";
7
7
  /**
8
8
  * Prints a single section item with its associated metadata.
9
9
  *
@@ -34,7 +34,7 @@ export declare const printSectionItems: <V>(values: V | V[], options: PrintTypeO
34
34
  *
35
35
  * @template V - Type of the values being printed
36
36
  */
37
- export declare const printSection: <V>(values: V[] | readonly V[], section: string, options: PrintTypeOptions) => string | MDXString;
37
+ export declare const printSection: <V>(values: V[] | readonly V[], section: string, options: PrintTypeOptions) => Maybe<PageSection>;
38
38
  /**
39
39
  * Prints a metadata section with special handling for deprecated items.
40
40
  *
@@ -47,5 +47,5 @@ export declare const printSection: <V>(values: V[] | readonly V[], section: stri
47
47
  * @template T - Type of the parent element
48
48
  * @template V - Type of the values being printed
49
49
  */
50
- export declare const printMetadataSection: <T, V>(type: T, values: V | V[] | readonly V[], section: string, options: PrintTypeOptions) => string | MDXString;
50
+ export declare const printMetadataSection: <T, V>(type: T, values: V | V[] | readonly V[], section: string, options: PrintTypeOptions) => Maybe<PageSection>;
51
51
  //# sourceMappingURL=section.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../src/section.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,gBAAgB,EAEjB,MAAM,yBAAyB,CAAC;AAuBjC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,2DAmDjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,mEAwBlC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,+FAqC7B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,CAAC,4GAsDxC,CAAC"}
1
+ {"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../src/section.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,KAAK,EACL,SAAS,EACT,WAAW,EACX,gBAAgB,EAEjB,MAAM,yBAAyB,CAAC;AAuBjC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,2DAmDjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,mEAoBlC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,+FAyC7B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,CAAC,4GA0ExC,CAAC"}
package/dist/section.js CHANGED
@@ -72,11 +72,7 @@ const printSectionItems = (values, options) => {
72
72
  return "";
73
73
  }
74
74
  const level = ("level" in options && typeof options.level === "number" ? options.level : 4);
75
- const items = values
76
- .filter((v) => {
77
- return v;
78
- })
79
- .map((v) => {
75
+ const items = values.filter(Boolean).map((v) => {
80
76
  return (0, exports.printSectionItem)(v, {
81
77
  ...options,
82
78
  level,
@@ -97,7 +93,7 @@ exports.printSectionItems = printSectionItems;
97
93
  */
98
94
  const printSection = (values, section, options) => {
99
95
  if (!Array.isArray(values) || values.length === 0) {
100
- return "";
96
+ return undefined;
101
97
  }
102
98
  const level = ("level" in options && typeof options.level === "number" ? options.level : 3);
103
99
  const [openSection, closeSection] = (() => {
@@ -105,7 +101,7 @@ const printSection = (values, section, options) => {
105
101
  typeof options.collapsible.dataClose === "string") {
106
102
  return options.formatMDXDetails(options.collapsible).split(`\r`);
107
103
  }
108
- return [strings_1.MARKDOWN_EOP, strings_1.MARKDOWN_EOP];
104
+ return ["", strings_1.MARKDOWN_EOP];
109
105
  })();
110
106
  const items = (0, exports.printSectionItems)(values, {
111
107
  ...options,
@@ -113,9 +109,13 @@ const printSection = (values, section, options) => {
113
109
  level: level >= 3 && level <= 5 ? (level + 1) : undefined,
114
110
  });
115
111
  if (items === "") {
116
- return ""; // do not print section is no items printed
112
+ return undefined; // do not print section is no items printed
117
113
  }
118
- return `${options_1.SectionLevels.LEVEL.repeat(level)} ${section}${openSection}${items}${closeSection}`;
114
+ return {
115
+ title: section,
116
+ content: `${openSection}${items}${closeSection}`,
117
+ level,
118
+ };
119
119
  };
120
120
  exports.printSection = printSection;
121
121
  /**
@@ -136,7 +136,7 @@ const printMetadataSection = (type, values, section, options) => {
136
136
  !("name" in type) ||
137
137
  !Array.isArray(values) ||
138
138
  values.length === 0) {
139
- return "";
139
+ return undefined;
140
140
  }
141
141
  switch (options.deprecated) {
142
142
  case "group": {
@@ -162,7 +162,22 @@ const printMetadataSection = (type, values, section, options) => {
162
162
  dataClose: strings_1.DEPRECATED,
163
163
  },
164
164
  });
165
- return `${meta}${deprecatedMeta}`;
165
+ const content = [meta?.content, deprecatedMeta?.content]
166
+ .filter((entry) => {
167
+ return typeof entry === "string";
168
+ })
169
+ .join("");
170
+ if (content.trim().length === 0) {
171
+ return undefined;
172
+ }
173
+ const level = ("level" in options && typeof options.level === "number"
174
+ ? options.level
175
+ : 3);
176
+ return {
177
+ title: section,
178
+ content,
179
+ level,
180
+ };
166
181
  }
167
182
  case "default":
168
183
  default:
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "bugs": {
6
6
  "url": "https://github.com/graphql-markdown/graphql-markdown/issues"
7
7
  },
8
- "version": "1.14.0",
8
+ "version": "1.15.0",
9
9
  "license": "MIT",
10
10
  "repository": {
11
11
  "type": "git",
@@ -51,15 +51,26 @@
51
51
  "scripts": {
52
52
  "stryker": "stryker run",
53
53
  "clean": "tsgo --build --clean && rm -rf ./dist",
54
- "docs": "typedoc",
55
- "build": "tsgo --build"
54
+ "docs": "typedoc --options typedoc.config.mjs",
55
+ "build": "tsgo --build",
56
+ "lint": "eslint --config ../../packages/tooling-config/eslint/config.ts \"{src,tests}/**/*.{ts,js,json,gql}\"",
57
+ "lint:fix": "eslint --config ../../packages/tooling-config/eslint/config.ts \"{src,tests}/**/*.{ts,js,json,gql}\" --fix",
58
+ "prettier": "prettier \"{src,tests,assets}/**/*.{ts,js,json,md,gql}\" --check",
59
+ "prettier:fix": "prettier \"{src,tests,assets}/**/*.{ts,js,json,md,gql}\" --write",
60
+ "ts:check": "tsgo --noEmit",
61
+ "test": "jest",
62
+ "test:unit": "jest --passWithNoTests --testPathPatterns=tests/unit",
63
+ "test:integration": "jest --passWithNoTests --testPathPatterns=tests/integration",
64
+ "test:ci": "jest --passWithNoTests --ci --silent --randomize --runInBand",
65
+ "test:watch": "jest --watch"
56
66
  },
57
67
  "dependencies": {
58
- "@graphql-markdown/graphql": "^1.1.9",
59
- "@graphql-markdown/utils": "^1.9.2"
68
+ "@graphql-markdown/graphql": "^1.2.1",
69
+ "@graphql-markdown/types": "^1.12.0",
70
+ "@graphql-markdown/utils": "^1.11.0"
60
71
  },
61
72
  "devDependencies": {
62
- "@graphql-markdown/types": "^1.10.1"
73
+ "@graphql-markdown/tooling-config": "^1.0.0"
63
74
  },
64
75
  "resolutions": {
65
76
  "micromatch": "4.0.8"