@graphql-markdown/printer-legacy 1.16.2 → 1.18.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.
package/dist/printer.d.ts CHANGED
@@ -9,7 +9,7 @@
9
9
  */
10
10
  import type { Formatter, GraphQLSchema, IPrinter, Maybe, MDXString, PageSection, PrinterEventEmitter, PrinterInitOptions, PrintTypeOptions } from "@graphql-markdown/types";
11
11
  import { printDescription } from "./common";
12
- import { printCustomDirectives, printCustomTags } from "./directive";
12
+ import { printDecorators } from "./decorator";
13
13
  /**
14
14
  * The Printer class implements the core functionality for generating Markdown documentation
15
15
  * from GraphQL schema types.
@@ -34,13 +34,9 @@ export declare class Printer implements IPrinter {
34
34
  */
35
35
  static readonly printDescription: typeof printDescription;
36
36
  /**
37
- * Prints custom directives
37
+ * Prints predicate-driven decorators
38
38
  */
39
- static readonly printCustomDirectives: typeof printCustomDirectives;
40
- /**
41
- * Prints custom tags
42
- */
43
- static readonly printCustomTags: typeof printCustomTags;
39
+ static readonly printDecorators: typeof printDecorators;
44
40
  private static _eventEmitter;
45
41
  private static _options;
46
42
  private static _mdxDeclaration;
@@ -72,7 +68,7 @@ export declare class Printer implements IPrinter {
72
68
  * @param mdxDeclaration - Optional MDX import declaration
73
69
  * @param eventEmitter - Optional event emitter for print events interception
74
70
  */
75
- static init(schema: Maybe<GraphQLSchema>, baseURL?: Maybe<string>, linkRoot?: Maybe<string>, { customDirectives, deprecated, groups, meta, metatags, onlyDocDirectives, printTypeOptions, skipDocDirectives, sectionHeaderId, }?: PrinterInitOptions, formatter?: Partial<Formatter>, mdxDeclaration?: Maybe<string>, eventEmitter?: Maybe<PrinterEventEmitter>): Promise<void>;
71
+ static init(schema: Maybe<GraphQLSchema>, baseURL?: Maybe<string>, linkRoot?: Maybe<string>, { decorators, deprecated, groups, meta, metatags, onlyDocDirectives, printTypeOptions, skipDocDirectives, sectionHeaderId, }?: PrinterInitOptions, formatter?: Partial<Formatter>, mdxDeclaration?: Maybe<string>, eventEmitter?: Maybe<PrinterEventEmitter>): Promise<void>;
76
72
  /**
77
73
  * Prints the header section of a type documentation
78
74
  *
@@ -174,15 +170,34 @@ export declare class Printer implements IPrinter {
174
170
  */
175
171
  static readonly printType: (name: Maybe<string>, type: unknown, options?: Maybe<Partial<PrintTypeOptions>>) => Promise<Maybe<MDXString>>;
176
172
  /**
177
- * Renders a page section, optionally prefixing a heading when a title is present.
173
+ * Renders a page section into markdown text.
174
+ *
175
+ * Accepts a nullable section-like value and safely normalizes it into a string.
176
+ * If the section has a valid `title`, a markdown heading is prefixed using the
177
+ * provided `level` (defaulting to 3). If no valid title exists, only content is returned.
178
+ *
179
+ * Content can be a string, a nested section object, or an array of nested entries.
180
+ * Nested content is rendered recursively by calling `renderPageSection` for each child.
181
+ * Invalid, unsupported, or effectively empty inputs return an empty string.
182
+ *
183
+ * @param section - A nullable page section value to render. Supports nested structures.
184
+ * @returns The rendered markdown for the section, or an empty string when nothing renderable exists.
178
185
  */
179
186
  private static readonly renderPageSection;
180
187
  /**
181
- * Runtime guard for built-in page content section keys.
188
+ * Runtime type guard for built-in type page content section keys.
189
+ *
190
+ * A value qualifies as a valid content section when it is a string key
191
+ * included in `TYPE_PAGE_SECTION_ORDER` (that is, one of the built-in
192
+ * content sections used when rendering type pages).
182
193
  */
183
194
  private static readonly isTypePageContentSection;
184
195
  /**
185
- * Runtime guard for header-only page section keys.
196
+ * Runtime type guard for header-only type page section keys.
197
+ *
198
+ * A value is considered a valid header section when it is a string and
199
+ * matches one of the built-in header keys defined in `TYPE_PAGE_HEADER_ORDER`.
200
+ * Returning `true` narrows `section` to `TypePageHeaderSection`.
186
201
  */
187
202
  private static readonly isTypePageHeaderSection;
188
203
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"printer.d.ts","sourceRoot":"","sources":["../src/printer.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"printer.d.ts","sourceRoot":"","sources":["../src/printer.ts"],"names":[],"mappings":"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"}
package/dist/printer.js CHANGED
@@ -31,7 +31,6 @@ const TYPE_PAGE_SECTION_ORDER = [
31
31
  "tags",
32
32
  "description",
33
33
  "code",
34
- "customDirectives",
35
34
  "metadata",
36
35
  "example",
37
36
  "relations",
@@ -40,24 +39,36 @@ const graphql_1 = require("@graphql-markdown/graphql");
40
39
  const utils_1 = require("@graphql-markdown/utils");
41
40
  const relation_1 = require("./relation");
42
41
  const common_1 = require("./common");
43
- const directive_1 = require("./directive");
42
+ const decorator_1 = require("./decorator");
44
43
  const frontmatter_1 = require("./frontmatter");
45
44
  const graphql_2 = require("./graphql");
46
45
  const link_1 = require("./link");
47
46
  const strings_1 = require("./const/strings");
48
47
  const formatter_1 = require("./formatter");
49
48
  const options_1 = require("./const/options");
50
- const example_1 = require("./example");
51
49
  const events_1 = require("./events");
52
50
  /**
53
51
  * Default initialization options for the Printer class.
54
52
  * @internal
55
53
  */
56
54
  const DEFAULT_INIT_OPTIONS = {
57
- customDirectives: undefined,
58
55
  groups: undefined,
59
56
  sectionHeaderId: true,
60
57
  };
58
+ /**
59
+ * Normalizes the configured hierarchy option into the canonical object form.
60
+ *
61
+ * Supported string presets are:
62
+ * - `"entity"`: entity-centric hierarchy grouping.
63
+ * - `"flat"`: no hierarchy grouping (flat output structure).
64
+ * - `"api"`: API-oriented hierarchy grouping.
65
+ *
66
+ * If `hierarchy` is already an object, it is returned as-is. If it is missing
67
+ * or not one of the supported string presets, `undefined` is returned.
68
+ *
69
+ * @param hierarchy - Hierarchy configuration from print type options.
70
+ * @returns The normalized hierarchy object, or `undefined` when not applicable.
71
+ */
61
72
  const normalizeHierarchy = (hierarchy) => {
62
73
  if (!hierarchy) {
63
74
  return undefined;
@@ -100,13 +111,9 @@ class Printer {
100
111
  */
101
112
  static printDescription = common_1.printDescription;
102
113
  /**
103
- * Prints custom directives
104
- */
105
- static printCustomDirectives = directive_1.printCustomDirectives;
106
- /**
107
- * Prints custom tags
114
+ * Prints predicate-driven decorators
108
115
  */
109
- static printCustomTags = directive_1.printCustomTags;
116
+ static printDecorators = decorator_1.printDecorators;
110
117
  static _eventEmitter;
111
118
  static _options;
112
119
  static _mdxDeclaration;
@@ -150,14 +157,14 @@ class Printer {
150
157
  * @param mdxDeclaration - Optional MDX import declaration
151
158
  * @param eventEmitter - Optional event emitter for print events interception
152
159
  */
153
- static async init(schema, baseURL = "schema", linkRoot = "/", { customDirectives, deprecated, groups, meta, metatags, onlyDocDirectives, printTypeOptions, skipDocDirectives, sectionHeaderId, } = DEFAULT_INIT_OPTIONS, formatter, mdxDeclaration, eventEmitter) {
160
+ static async init(schema, baseURL = "schema", linkRoot = "/", { decorators, deprecated, groups, meta, metatags, onlyDocDirectives, printTypeOptions, skipDocDirectives, sectionHeaderId, } = DEFAULT_INIT_OPTIONS, formatter, mdxDeclaration, eventEmitter) {
154
161
  // Always update eventEmitter regardless of initialization state
155
162
  Printer.eventEmitter = eventEmitter ?? null;
156
163
  if (Printer.options === undefined) {
157
164
  Printer.options = {
158
165
  ...options_1.DEFAULT_OPTIONS,
159
166
  basePath: utils_1.pathUrl.join(linkRoot ?? "", baseURL ?? ""),
160
- customDirectives,
167
+ decorators,
161
168
  exampleSection: typeof printTypeOptions?.exampleSection === "object"
162
169
  ? printTypeOptions.exampleSection
163
170
  : undefined,
@@ -284,14 +291,7 @@ class Printer {
284
291
  * @returns Example page section or undefined when no example is available
285
292
  */
286
293
  static printExample = (type, options) => {
287
- const example = (0, example_1.printExample)(type, options);
288
- if (!example) {
289
- return undefined;
290
- }
291
- return {
292
- content: `${strings_1.MARKDOWN_SOC}${example}${strings_1.MARKDOWN_EOC}${strings_1.MARKDOWN_EOP}`,
293
- title: "Example",
294
- };
294
+ return (0, decorator_1.printDecorator)(type, (0, decorator_1.getExampleSectionDefinition)(), options);
295
295
  };
296
296
  /**
297
297
  * Prints metadata information for a GraphQL type
@@ -409,12 +409,20 @@ class Printer {
409
409
  // can add, remove, or reorder them at will.
410
410
  // See: https://github.com/graphql-markdown/graphql-markdown/issues/2954
411
411
  const code = await Printer.printCodeAsync(type, name, printTypeOptions);
412
- const customDirectives = Printer.printCustomDirectives(type, printTypeOptions);
413
- const tags = Printer.printCustomTags(type, printTypeOptions);
412
+ // `customDirective`'s `tag` handlers reach this line via the decorators
413
+ // pipeline (`printSlotDecorators`, not a dedicated call) — see
414
+ // `buildCustomDirectiveDecorators` in `./decorator`.
415
+ const tags = (0, decorator_1.printSlotDecorators)("tags", type, printTypeOptions)
416
+ .filter(Boolean)
417
+ .join(" ");
414
418
  const metadata = Printer.printTypeMetadata(type, printTypeOptions);
415
419
  const relations = Printer.printRelations(type, printTypeOptions);
416
420
  const example = Printer.printExample(type, printTypeOptions);
417
- // Create sections map for composition events
421
+ // Create sections map for composition events. The built-in "Directives"
422
+ // section reaches this map via the `...Printer.printDecorators(...)`
423
+ // spread below (it is `customDirective`'s adapter, unconditionally
424
+ // present under the reserved `customDirectives` id — see
425
+ // `buildCustomDirectiveDecorators`), not a dedicated field here.
418
426
  const sections = {
419
427
  header: { content: header },
420
428
  metatags: { content: metatags },
@@ -422,12 +430,12 @@ class Printer {
422
430
  tags: Printer.normalizePageSection(tags),
423
431
  description: Printer.normalizePageSection(description),
424
432
  code: Printer.normalizePageSection(code),
425
- customDirectives: Printer.normalizePageSection(customDirectives),
426
433
  metadata: Printer.normalizePageSection(metadata),
427
434
  example: Printer.normalizePageSection(example),
428
435
  relations: Printer.normalizePageSection(relations),
436
+ ...Printer.printDecorators(type, printTypeOptions),
429
437
  };
430
- let sectionOrder = [...TYPE_PAGE_SECTION_ORDER];
438
+ let sectionOrder = (0, decorator_1.getDecoratorsOrder)(TYPE_PAGE_SECTION_ORDER, printTypeOptions);
431
439
  // Emit BEFORE_COMPOSE_PAGE_TYPE event if emitter is configured
432
440
  if (Printer.eventEmitter) {
433
441
  const beforeComposeEvent = new events_1.BeforeComposePageTypeEvent({ type, name, options: printTypeOptions, sections }, sectionOrder);
@@ -457,7 +465,18 @@ class Printer {
457
465
  return output;
458
466
  };
459
467
  /**
460
- * Renders a page section, optionally prefixing a heading when a title is present.
468
+ * Renders a page section into markdown text.
469
+ *
470
+ * Accepts a nullable section-like value and safely normalizes it into a string.
471
+ * If the section has a valid `title`, a markdown heading is prefixed using the
472
+ * provided `level` (defaulting to 3). If no valid title exists, only content is returned.
473
+ *
474
+ * Content can be a string, a nested section object, or an array of nested entries.
475
+ * Nested content is rendered recursively by calling `renderPageSection` for each child.
476
+ * Invalid, unsupported, or effectively empty inputs return an empty string.
477
+ *
478
+ * @param section - A nullable page section value to render. Supports nested structures.
479
+ * @returns The rendered markdown for the section, or an empty string when nothing renderable exists.
461
480
  */
462
481
  static renderPageSection = (section) => {
463
482
  if (!section ||
@@ -506,14 +525,22 @@ class Printer {
506
525
  return `${title}${content}`;
507
526
  };
508
527
  /**
509
- * Runtime guard for built-in page content section keys.
528
+ * Runtime type guard for built-in type page content section keys.
529
+ *
530
+ * A value qualifies as a valid content section when it is a string key
531
+ * included in `TYPE_PAGE_SECTION_ORDER` (that is, one of the built-in
532
+ * content sections used when rendering type pages).
510
533
  */
511
534
  static isTypePageContentSection = (section) => {
512
535
  return (typeof section === "string" &&
513
536
  TYPE_PAGE_SECTION_ORDER.includes(section));
514
537
  };
515
538
  /**
516
- * Runtime guard for header-only page section keys.
539
+ * Runtime type guard for header-only type page section keys.
540
+ *
541
+ * A value is considered a valid header section when it is a string and
542
+ * matches one of the built-in header keys defined in `TYPE_PAGE_HEADER_ORDER`.
543
+ * Returning `true` narrows `section` to `TypePageHeaderSection`.
517
544
  */
518
545
  static isTypePageHeaderSection = (section) => {
519
546
  return (typeof section === "string" &&
@@ -1 +1 @@
1
- {"version":3,"file":"relation.d.ts","sourceRoot":"","sources":["../src/relation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,KAAK,EACL,gBAAgB,EAGhB,UAAU,EACX,MAAM,yBAAyB,CAAC;AAgBjC;;;;;;;;GAQG;AAGH,eAAO,MAAM,2BAA2B,SAChC,MAAM,KACX,KAAK,CAAC,UAAU,CAOlB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AAGH,eAAO,MAAM,eAAe,GAAI,CAAC,QACzB,OAAO,WACJ,OAAO,eACH,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,WAC1B,gBAAgB,KACxB,SAAS,GAAG,MAmDd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,SACnB,OAAO,WACJ,gBAAgB,KACxB,SAAS,GAAG,MAgBd,CAAC"}
1
+ {"version":3,"file":"relation.d.ts","sourceRoot":"","sources":["../src/relation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,KAAK,EACL,gBAAgB,EAGhB,UAAU,EACX,MAAM,yBAAyB,CAAC;AAgBjC;;;;;;;;GAQG;AAEH,eAAO,MAAM,2BAA2B,SAChC,MAAM,KACX,KAAK,CAAC,UAAU,CAOlB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,eAAe,GAAI,CAAC,QACzB,OAAO,WACJ,OAAO,eACH,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,WAC1B,gBAAgB,KACxB,SAAS,GAAG,MAmDd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,SACnB,OAAO,WACJ,gBAAgB,KACxB,SAAS,GAAG,MAgBd,CAAC"}
package/dist/relation.js CHANGED
@@ -21,7 +21,6 @@ const options_1 = require("./const/options");
21
21
  * ```
22
22
  */
23
23
  // Used only by unit tests for direct whitebox coverage; not part of the production public API.
24
- // fallow-ignore-next-line unused-export
25
24
  const getRootTypeLocaleFromString = (text) => {
26
25
  for (const [type, props] of Object.entries(strings_1.ROOT_TYPE_LOCALE)) {
27
26
  if (Object.values(props).includes(text)) {
@@ -46,7 +45,6 @@ exports.getRootTypeLocaleFromString = getRootTypeLocaleFromString;
46
45
  * ```
47
46
  */
48
47
  // Used only by unit tests for direct whitebox coverage; not part of the production public API.
49
- // fallow-ignore-next-line unused-export
50
48
  const printRelationOf = (type, section, getRelation, options) => {
51
49
  if (!(0, graphql_1.isNamedType)(type) ||
52
50
  (0, graphql_1.isOperation)(type) ||
@@ -1 +1 @@
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;AAGH,eAAO,MAAM,gBAAgB,GAAI,CAAC,QAC1B,CAAC,WACE,gBAAgB,KACxB,SAAS,GAAG,MAgDd,CAAC;AAEF;;;;;;;;GAQG;AAGH,eAAO,MAAM,iBAAiB,GAAI,CAAC,UACzB,CAAC,GAAG,CAAC,EAAE,WACN,gBAAgB,KACxB,SAAS,GAAG,MAiBd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,UACpB,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,WACjB,MAAM,WACN,gBAAgB,KACxB,KAAK,CAAC,WAAW,CAmCnB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,CAAC,QACjC,CAAC,UACC,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,WACrB,MAAM,WACN,gBAAgB,KACxB,KAAK,CAAC,WAAW,CAqEnB,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;AA8CjC;;;;;;;;GAQG;AAEH,eAAO,MAAM,gBAAgB,GAAI,CAAC,QAC1B,CAAC,WACE,gBAAgB,KACxB,SAAS,GAAG,MAmEd,CAAC;AAEF;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,GAAI,CAAC,UACzB,CAAC,GAAG,CAAC,EAAE,WACN,gBAAgB,KACxB,SAAS,GAAG,MAiBd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,UACpB,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,WACjB,MAAM,WACN,gBAAgB,KACxB,KAAK,CAAC,WAAW,CAmCnB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,CAAC,QACjC,CAAC,UACC,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,WACrB,MAAM,WACN,gBAAgB,KACxB,KAAK,CAAC,WAAW,CAqEnB,CAAC"}
package/dist/section.js CHANGED
@@ -10,10 +10,26 @@ const utils_1 = require("@graphql-markdown/utils");
10
10
  const graphql_1 = require("@graphql-markdown/graphql");
11
11
  const common_1 = require("./common");
12
12
  const badge_1 = require("./badge");
13
+ const decorator_1 = require("./decorator");
13
14
  const link_1 = require("./link");
14
- const directive_1 = require("./directive");
15
15
  const strings_1 = require("./const/strings");
16
16
  const options_1 = require("./const/options");
17
+ /**
18
+ * Prints a permalink for the section header if enabled in the options.
19
+ *
20
+ * The permalink syntax is formatter specific, see `formatMDXPermalink`.
21
+ *
22
+ * @param id - The ID of the section header
23
+ * @param options - Configuration options for printing
24
+ * @returns Formatted permalink string or undefined if not applicable
25
+ */
26
+ const printPermalink = (id, options) => {
27
+ if (!options.sectionHeaderId || !id) {
28
+ return undefined;
29
+ }
30
+ const format = options.formatMDXPermalink ?? options_1.DEFAULT_OPTIONS.formatMDXPermalink;
31
+ return format(id);
32
+ };
17
33
  /**
18
34
  * Prints a single section item with its associated metadata.
19
35
  *
@@ -24,7 +40,6 @@ const options_1 = require("./const/options");
24
40
  * @template T - Type of the GraphQL element being printed
25
41
  */
26
42
  // Used only by unit tests for direct whitebox coverage; not part of the production public API.
27
- // fallow-ignore-next-line unused-export
28
43
  const printSectionItem = (type, options) => {
29
44
  const level = "level" in options && typeof options.level === "number" ? options.level : 4;
30
45
  if (!(0, link_1.hasPrintableDirective)(type, options)) {
@@ -35,13 +50,33 @@ const printSectionItem = (type, options) => {
35
50
  ...options,
36
51
  withAttributes: false,
37
52
  });
38
- const badges = (0, badge_1.printBadges)(type, options);
39
- const tags = (0, directive_1.printCustomTags)(type, options);
53
+ const badges = [
54
+ (0, badge_1.printBadges)(type, options),
55
+ ...(0, decorator_1.printSlotDecorators)("badges", type, options),
56
+ ]
57
+ .filter(Boolean)
58
+ .join(" ");
59
+ // `customDirective`'s `tag` handlers reach this line via the decorators
60
+ // pipeline (`printSlotDecorators`), not a dedicated call — see
61
+ // `buildCustomDirectiveDecorators` in `./decorator`.
62
+ const tags = (0, decorator_1.printSlotDecorators)("tags", type, options)
63
+ .filter(Boolean)
64
+ .join(" ");
40
65
  const parentTypeLink = (0, link_1.printParentLink)(type, options);
41
- const permalink = options.sectionHeaderId && link.id
42
- ? String.raw `\{#${link.id}\}`
43
- : undefined; // use raw string to prevent MDX from interpreting the curly braces as JSX
44
- const metadata = [badges, tags, permalink].filter(Boolean).join(" ");
66
+ const permalink = [
67
+ printPermalink(link.id, options),
68
+ ...(0, decorator_1.printSlotDecorators)("permalink", type, options),
69
+ ]
70
+ .filter(Boolean)
71
+ .join(" ");
72
+ const metadata = [
73
+ badges,
74
+ tags,
75
+ permalink,
76
+ ...(0, decorator_1.printSlotDecorators)("metadata", type, options),
77
+ ]
78
+ .filter(Boolean)
79
+ .join(" ");
45
80
  const title = `${options_1.SectionLevels.LEVEL.repeat(level)} ${typeNameLink}${parentTypeLink} ${metadata} ${strings_1.MARKDOWN_EOL}`;
46
81
  const description = (0, common_1.printDescription)(type, options, "")
47
82
  .trim()
@@ -70,7 +105,6 @@ exports.printSectionItem = printSectionItem;
70
105
  * @template V - Type of the values being printed
71
106
  */
72
107
  // Used only by unit tests for direct whitebox coverage; not part of the production public API.
73
- // fallow-ignore-next-line unused-export
74
108
  const printSectionItems = (values, options) => {
75
109
  if (!Array.isArray(values) || values.length === 0) {
76
110
  return "";
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.16.2",
8
+ "version": "1.18.0",
9
9
  "license": "MIT",
10
10
  "repository": {
11
11
  "type": "git",
@@ -1,44 +0,0 @@
1
- /**
2
- * Provides utilities for handling and printing GraphQL directives in Markdown format
3
- * @module
4
- */
5
- import type { Badge, PrintTypeOptions, MDXString, CustomDirectiveMapItem, CustomDirectiveResolver, Maybe, PageSection } from "@graphql-markdown/types";
6
- /**
7
- * Resolves a custom directive using the provided resolver function
8
- * @param resolver - The resolver function name to execute
9
- * @param type - The GraphQL type to resolve the directive for
10
- * @param constDirectiveOption - The directive configuration options
11
- * @param fallback - Optional fallback value if resolution fails
12
- * @returns The resolved directive value or `fallback`/`undefined`
13
- */
14
- export declare const getCustomDirectiveResolver: (resolver: CustomDirectiveResolver, type: unknown, constDirectiveOption: CustomDirectiveMapItem, fallback?: Maybe<string>) => Maybe<string>;
15
- /**
16
- * Prints a custom directive as a Markdown string
17
- * @param type - The GraphQL type to print the directive for
18
- * @param constDirectiveOption - The directive configuration options
19
- * @param options - General printing options
20
- * @returns Formatted Markdown string for the directive or `undefined`
21
- */
22
- export declare const printCustomDirective: (type: unknown, constDirectiveOption: CustomDirectiveMapItem, options: PrintTypeOptions) => Maybe<string>;
23
- /**
24
- * Prints all custom directives for a type as a Markdown section
25
- * @param type - The GraphQL type to print directives for
26
- * @param options - General printing options
27
- * @returns A "Directives" PageSection, or undefined when no directives are printable
28
- */
29
- export declare const printCustomDirectives: (type: unknown, options: PrintTypeOptions) => Maybe<PageSection>;
30
- /**
31
- * Extracts custom tags from directives for a given type
32
- * @param type - The GraphQL type to get tags for
33
- * @param options - General printing options
34
- * @returns Array of badge configurations from directive tags
35
- */
36
- export declare const getCustomTags: (type: unknown, options: PrintTypeOptions) => Badge[];
37
- /**
38
- * Prints custom directive tags as Markdown badges
39
- * @param type - The GraphQL type to print tags for
40
- * @param options - General printing options
41
- * @returns Formatted Markdown string of badges or empty string
42
- */
43
- export declare const printCustomTags: (type: unknown, options: PrintTypeOptions) => MDXString | string;
44
- //# sourceMappingURL=directive.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"directive.d.ts","sourceRoot":"","sources":["../src/directive.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,gBAAgB,EAChB,SAAS,EACT,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,EACL,WAAW,EACZ,MAAM,yBAAyB,CAAC;AASjC;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,aAC3B,uBAAuB,QAC3B,OAAO,wBACS,sBAAsB,aACjC,KAAK,CAAC,MAAM,CAAC,KACvB,KAAK,CAAC,MAAM,CAYd,CAAC;AAEF;;;;;;GAMG;AAGH,eAAO,MAAM,oBAAoB,SACzB,OAAO,wBACS,sBAAsB,WACnC,gBAAgB,KACxB,KAAK,CAAC,MAAM,CAgBd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,SAC1B,OAAO,WACJ,gBAAgB,KACxB,KAAK,CAAC,WAAW,CA6BnB,CAAC;AAEF;;;;;GAKG;AAGH,eAAO,MAAM,aAAa,SAClB,OAAO,WACJ,gBAAgB,KACxB,KAAK,EAqBP,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,SACpB,OAAO,WACJ,gBAAgB,KACxB,SAAS,GAAG,MAEd,CAAC"}
package/dist/directive.js DELETED
@@ -1,112 +0,0 @@
1
- "use strict";
2
- /**
3
- * Provides utilities for handling and printing GraphQL directives in Markdown format
4
- * @module
5
- */
6
- Object.defineProperty(exports, "__esModule", { value: true });
7
- exports.printCustomTags = exports.getCustomTags = exports.printCustomDirectives = exports.printCustomDirective = exports.getCustomDirectiveResolver = void 0;
8
- const graphql_1 = require("@graphql-markdown/graphql");
9
- const strings_1 = require("./const/strings");
10
- const options_1 = require("./const/options");
11
- const link_1 = require("./link");
12
- const badge_1 = require("./badge");
13
- /**
14
- * Resolves a custom directive using the provided resolver function
15
- * @param resolver - The resolver function name to execute
16
- * @param type - The GraphQL type to resolve the directive for
17
- * @param constDirectiveOption - The directive configuration options
18
- * @param fallback - Optional fallback value if resolution fails
19
- * @returns The resolved directive value or `fallback`/`undefined`
20
- */
21
- const getCustomDirectiveResolver = (resolver, type, constDirectiveOption, fallback) => {
22
- if (typeof constDirectiveOption.type !== "object" ||
23
- typeof constDirectiveOption[resolver] !== "function") {
24
- return fallback;
25
- }
26
- return constDirectiveOption[resolver](constDirectiveOption.type, type);
27
- };
28
- exports.getCustomDirectiveResolver = getCustomDirectiveResolver;
29
- /**
30
- * Prints a custom directive as a Markdown string
31
- * @param type - The GraphQL type to print the directive for
32
- * @param constDirectiveOption - The directive configuration options
33
- * @param options - General printing options
34
- * @returns Formatted Markdown string for the directive or `undefined`
35
- */
36
- // Used only by unit tests for direct whitebox coverage; not part of the production public API.
37
- // fallow-ignore-next-line unused-export
38
- const printCustomDirective = (type, constDirectiveOption, options) => {
39
- const typeNameLink = (0, link_1.printLink)(constDirectiveOption.type, {
40
- ...options,
41
- withAttributes: false,
42
- });
43
- const description = (0, exports.getCustomDirectiveResolver)("descriptor", type, constDirectiveOption);
44
- if (typeof description !== "string") {
45
- return undefined;
46
- }
47
- return `${options_1.SectionLevels.LEVEL.repeat(4)} ${typeNameLink}${strings_1.MARKDOWN_EOL} ${description}${strings_1.MARKDOWN_EOL} `;
48
- };
49
- exports.printCustomDirective = printCustomDirective;
50
- /**
51
- * Prints all custom directives for a type as a Markdown section
52
- * @param type - The GraphQL type to print directives for
53
- * @param options - General printing options
54
- * @returns A "Directives" PageSection, or undefined when no directives are printable
55
- */
56
- const printCustomDirectives = (type, options) => {
57
- const constDirectiveMap = (0, graphql_1.getConstDirectiveMap)(type, options.customDirectives);
58
- if (!constDirectiveMap || Object.keys(constDirectiveMap).length === 0) {
59
- return undefined;
60
- }
61
- const directives = Object.values(constDirectiveMap)
62
- .map((constDirectiveOption) => {
63
- return (0, exports.printCustomDirective)(type, constDirectiveOption, options);
64
- })
65
- .filter((value) => {
66
- return value !== undefined;
67
- });
68
- if (directives.length === 0) {
69
- return undefined;
70
- }
71
- const content = directives.join(strings_1.MARKDOWN_EOP);
72
- return {
73
- title: "Directives",
74
- content: `${content}${strings_1.MARKDOWN_EOP}`,
75
- level: 3,
76
- };
77
- };
78
- exports.printCustomDirectives = printCustomDirectives;
79
- /**
80
- * Extracts custom tags from directives for a given type
81
- * @param type - The GraphQL type to get tags for
82
- * @param options - General printing options
83
- * @returns Array of badge configurations from directive tags
84
- */
85
- // Used only by unit tests for direct whitebox coverage; not part of the production public API.
86
- // fallow-ignore-next-line unused-export
87
- const getCustomTags = (type, options) => {
88
- const constDirectiveMap = (0, graphql_1.getConstDirectiveMap)(type, options.customDirectives);
89
- if (typeof constDirectiveMap !== "object" ||
90
- constDirectiveMap === null ||
91
- Object.keys(constDirectiveMap).length === 0) {
92
- return [];
93
- }
94
- return Object.values(constDirectiveMap)
95
- .map((constDirectiveOption) => {
96
- return (0, exports.getCustomDirectiveResolver)("tag", type, constDirectiveOption);
97
- })
98
- .filter((value) => {
99
- return value !== undefined;
100
- });
101
- };
102
- exports.getCustomTags = getCustomTags;
103
- /**
104
- * Prints custom directive tags as Markdown badges
105
- * @param type - The GraphQL type to print tags for
106
- * @param options - General printing options
107
- * @returns Formatted Markdown string of badges or empty string
108
- */
109
- const printCustomTags = (type, options) => {
110
- return (0, badge_1.formatBadges)((0, exports.getCustomTags)(type, options), options);
111
- };
112
- exports.printCustomTags = printCustomTags;