@graphql-markdown/printer-legacy 1.12.0 → 1.12.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.
package/dist/printer.js CHANGED
@@ -1,4 +1,13 @@
1
1
  "use strict";
2
+ /**
3
+ * GraphQL Schema Printer Module
4
+ *
5
+ * This module provides functionality for printing GraphQL schema types into Markdown documentation.
6
+ * It includes utilities for handling various GraphQL types, custom directives, and formatting options.
7
+ *
8
+ * @module printer
9
+ * @packageDocumentation
10
+ */
2
11
  Object.defineProperty(exports, "__esModule", { value: true });
3
12
  exports.Printer = void 0;
4
13
  const graphql_1 = require("@graphql-markdown/graphql");
@@ -13,12 +22,59 @@ const strings_1 = require("./const/strings");
13
22
  const mdx_1 = require("./mdx");
14
23
  const options_1 = require("./const/options");
15
24
  const example_1 = require("./example");
25
+ /**
26
+ * The Printer class implements the core functionality for generating Markdown documentation
27
+ * from GraphQL schema types.
28
+ *
29
+ * @remarks
30
+ * This class provides static methods for rendering different components of the documentation:
31
+ * - Headers and frontmatter
32
+ * - Type descriptions and code blocks
33
+ * - Custom directives and metadata
34
+ * - Examples and relations
35
+ *
36
+ * @example
37
+ * ```typescript
38
+ * const printer = new Printer();
39
+ * await printer.init(schema, '/docs', 'graphql', options);
40
+ * const docs = printer.printType('Query', queryType);
41
+ * ```
42
+ */
16
43
  class Printer {
44
+ /**
45
+ * Global printer configuration options
46
+ * @static
47
+ */
17
48
  static options;
49
+ /**
50
+ * Prints type descriptions
51
+ * @static
52
+ */
18
53
  static printDescription = common_1.printDescription;
54
+ /**
55
+ * Prints custom directives
56
+ * @static
57
+ */
19
58
  static printCustomDirectives = directive_1.printCustomDirectives;
59
+ /**
60
+ * Prints custom tags
61
+ * @static
62
+ */
20
63
  static printCustomTags = directive_1.printCustomTags;
64
+ /**
65
+ * MDX module configuration
66
+ * @static
67
+ */
21
68
  static printMDXModule;
69
+ /**
70
+ * Initializes the printer with the given schema and configuration.
71
+ *
72
+ * @param schema - GraphQL schema to generate documentation for
73
+ * @param baseURL - Base URL path for documentation, e.g. '/docs'
74
+ * @param linkRoot - Root path for generating links between types
75
+ * @param options - Configuration options for the printer
76
+ * @param mdxParser - Optional MDX parser module for MDX output support
77
+ */
22
78
  static async init(schema, baseURL = "schema", linkRoot = "/", { customDirectives, groups, meta, metatags, onlyDocDirectives, printTypeOptions, skipDocDirectives, } = {
23
79
  customDirectives: undefined,
24
80
  groups: undefined,
@@ -49,6 +105,14 @@ class Printer {
49
105
  };
50
106
  Printer.printMDXModule = await (0, mdx_1.mdxModule)(mdxParser);
51
107
  }
108
+ /**
109
+ * Prints the header section of a type documentation
110
+ *
111
+ * @param id - Unique identifier for the type
112
+ * @param title - Display title for the type
113
+ * @param options - Printer configuration options
114
+ * @returns Formatted header string with optional frontmatter
115
+ */
52
116
  static printHeader = (id, title, options) => {
53
117
  if (options.frontMatter === false) {
54
118
  return `# ${title}${strings_1.MARKDOWN_EOP}`;
@@ -56,6 +120,13 @@ class Printer {
56
120
  const fmOptions = options.frontMatter ?? options_1.DEFAULT_OPTIONS.frontMatter;
57
121
  return (0, frontmatter_1.printFrontMatter)(title, { ...fmOptions, id }, options);
58
122
  };
123
+ /**
124
+ * Prints the GraphQL type definition as code block
125
+ *
126
+ * @param type - GraphQL type to print
127
+ * @param options - Printer configuration options
128
+ * @returns Formatted code block string with type definition
129
+ */
59
130
  static printCode = (type, options) => {
60
131
  let code = "";
61
132
  if (typeof options.codeSection === "undefined" ||
@@ -92,6 +163,13 @@ class Printer {
92
163
  }
93
164
  return strings_1.MARKDOWN_SOC + code.trim() + strings_1.MARKDOWN_EOC;
94
165
  };
166
+ /**
167
+ * Prints example usage of the type if available
168
+ *
169
+ * @param type - GraphQL type to generate example for
170
+ * @param options - Printer configuration options
171
+ * @returns Formatted example section string or empty string if no example
172
+ */
95
173
  static printExample = (type, options) => {
96
174
  if (typeof options.exampleSection === "undefined" ||
97
175
  options.exampleSection === null ||
@@ -104,6 +182,14 @@ class Printer {
104
182
  }
105
183
  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}`;
106
184
  };
185
+ /**
186
+ * Prints metadata information for a GraphQL type
187
+ *
188
+ * @param type - GraphQL type to print metadata for
189
+ * @param options - Printer configuration options
190
+ * @returns Formatted metadata string as MDX or plain string
191
+ * @throws {Error} When type is not supported
192
+ */
107
193
  static printTypeMetadata = (type, options) => {
108
194
  switch (true) {
109
195
  case (0, graphql_1.isScalarType)(type):
@@ -126,12 +212,26 @@ class Printer {
126
212
  return "";
127
213
  }
128
214
  };
215
+ /**
216
+ * Prints related type information
217
+ *
218
+ * @param type - GraphQL type to find relations for
219
+ * @param options - Printer configuration options
220
+ * @returns Formatted relations section as MDX or plain string
221
+ */
129
222
  static printRelations = (type, options) => {
130
223
  if (options.relatedTypeSection !== true) {
131
224
  return "";
132
225
  }
133
226
  return (0, relation_1.printRelations)(type, options);
134
227
  };
228
+ /**
229
+ * Prints HTML meta tags for the documentation
230
+ *
231
+ * @param _type - GraphQL type (unused)
232
+ * @param options - Printer configuration options containing metatags
233
+ * @returns Formatted HTML meta tags string
234
+ */
135
235
  static printMetaTags = (_type, { metatags }) => {
136
236
  if (!metatags || metatags.length < 1) {
137
237
  return "";
@@ -144,6 +244,33 @@ class Printer {
144
244
  });
145
245
  return ["<head>", ...meta, "</head>"].join(strings_1.MARKDOWN_EOL);
146
246
  };
247
+ /**
248
+ * Main method to print complete documentation for a GraphQL type
249
+ *
250
+ * @param name - Name identifier for the type
251
+ * @param type - GraphQL type to generate documentation for
252
+ * @param options - Optional printer configuration options
253
+ * @returns Complete documentation as MDX string or undefined if type should be skipped
254
+ *
255
+ * @example
256
+ * ```typescript
257
+ * const doc = Printer.printType('User', UserType, {
258
+ * frontMatter: true,
259
+ * codeSection: true
260
+ * });
261
+ * ```
262
+ *
263
+ * @remarks
264
+ * The method combines multiple sections:
265
+ * - Header with frontmatter
266
+ * - Meta tags
267
+ * - Description
268
+ * - Code definition
269
+ * - Custom directives
270
+ * - Type metadata
271
+ * - Example usage
272
+ * - Related types
273
+ */
147
274
  static printType = (name, type, options) => {
148
275
  const printTypeOptions = {
149
276
  ...options_1.DEFAULT_OPTIONS,
@@ -1,4 +1,43 @@
1
+ /**
2
+ * This module provides functionality to print relationships between GraphQL types,
3
+ * including return types, member fields, and implementations, in a formatted MDX string output.
4
+ * @module
5
+ */
1
6
  import type { IGetRelation, MDXString, Maybe, PrintTypeOptions, TypeLocale } from "@graphql-markdown/types";
7
+ /**
8
+ * Converts a string representation of a root type to its corresponding TypeLocale
9
+ * @param text - The string to convert to a TypeLocale
10
+ * @returns The matching TypeLocale if found, undefined otherwise
11
+ * @example
12
+ * ```ts
13
+ * const locale = getRootTypeLocaleFromString('Query');
14
+ * ```
15
+ */
2
16
  export declare const getRootTypeLocaleFromString: (text: string) => Maybe<TypeLocale>;
17
+ /**
18
+ * Prints the relation section for a specific type and relation category
19
+ * @template T - Type of the relation
20
+ * @param type - The GraphQL type to get relations for
21
+ * @param section - The section title for the relation
22
+ * @param getRelation - Function to retrieve relations of type T
23
+ * @param options - Printing options for type formatting
24
+ * @returns {MDXString | string} Formatted MDX string containing the relations or empty string if no relations found
25
+ * @throws {Error} If the schema is not provided in options
26
+ * @example
27
+ * ```ts
28
+ * const mdx = printRelationOf(type, "Member Of", getRelationOfField, options);
29
+ * ```
30
+ */
3
31
  export declare const printRelationOf: <T>(type: unknown, section: unknown, getRelation: Maybe<IGetRelation<T>>, options: PrintTypeOptions) => MDXString | string;
32
+ /**
33
+ * Prints all relations (return types, member fields, and implementations) for a given type
34
+ * @param type - The GraphQL type to get all relations for
35
+ * @param options - Printing options for type formatting
36
+ * @returns Formatted MDX string containing all relations or empty string if no relations found
37
+ * @throws If the schema is not provided in options
38
+ * @example
39
+ * ```ts
40
+ * const relations = printRelations(myType, { schema, formatMDXBullet: () => "* " });
41
+ * ```
42
+ */
4
43
  export declare const printRelations: (type: unknown, options: PrintTypeOptions) => MDXString | string;
package/dist/relation.js CHANGED
@@ -1,4 +1,9 @@
1
1
  "use strict";
2
+ /**
3
+ * This module provides functionality to print relationships between GraphQL types,
4
+ * including return types, member fields, and implementations, in a formatted MDX string output.
5
+ * @module
6
+ */
2
7
  Object.defineProperty(exports, "__esModule", { value: true });
3
8
  exports.printRelations = exports.printRelationOf = exports.getRootTypeLocaleFromString = void 0;
4
9
  const graphql_1 = require("@graphql-markdown/graphql");
@@ -6,6 +11,15 @@ const link_1 = require("./link");
6
11
  const badge_1 = require("./badge");
7
12
  const strings_1 = require("./const/strings");
8
13
  const options_1 = require("./const/options");
14
+ /**
15
+ * Converts a string representation of a root type to its corresponding TypeLocale
16
+ * @param text - The string to convert to a TypeLocale
17
+ * @returns The matching TypeLocale if found, undefined otherwise
18
+ * @example
19
+ * ```ts
20
+ * const locale = getRootTypeLocaleFromString('Query');
21
+ * ```
22
+ */
9
23
  const getRootTypeLocaleFromString = (text) => {
10
24
  for (const [type, props] of Object.entries(strings_1.ROOT_TYPE_LOCALE)) {
11
25
  if (Object.values(props).includes(text)) {
@@ -15,6 +29,20 @@ const getRootTypeLocaleFromString = (text) => {
15
29
  return undefined;
16
30
  };
17
31
  exports.getRootTypeLocaleFromString = getRootTypeLocaleFromString;
32
+ /**
33
+ * Prints the relation section for a specific type and relation category
34
+ * @template T - Type of the relation
35
+ * @param type - The GraphQL type to get relations for
36
+ * @param section - The section title for the relation
37
+ * @param getRelation - Function to retrieve relations of type T
38
+ * @param options - Printing options for type formatting
39
+ * @returns {MDXString | string} Formatted MDX string containing the relations or empty string if no relations found
40
+ * @throws {Error} If the schema is not provided in options
41
+ * @example
42
+ * ```ts
43
+ * const mdx = printRelationOf(type, "Member Of", getRelationOfField, options);
44
+ * ```
45
+ */
18
46
  const printRelationOf = (type, section, getRelation, options) => {
19
47
  if (!(0, graphql_1.isNamedType)(type) ||
20
48
  (0, graphql_1.isOperation)(type) ||
@@ -53,6 +81,17 @@ const printRelationOf = (type, section, getRelation, options) => {
53
81
  return `${options_1.SectionLevels.LEVEL.repeat(3)} ${section}${strings_1.MARKDOWN_EOP}${content}${strings_1.MARKDOWN_EOP}`;
54
82
  };
55
83
  exports.printRelationOf = printRelationOf;
84
+ /**
85
+ * Prints all relations (return types, member fields, and implementations) for a given type
86
+ * @param type - The GraphQL type to get all relations for
87
+ * @param options - Printing options for type formatting
88
+ * @returns Formatted MDX string containing all relations or empty string if no relations found
89
+ * @throws If the schema is not provided in options
90
+ * @example
91
+ * ```ts
92
+ * const relations = printRelations(myType, { schema, formatMDXBullet: () => "* " });
93
+ * ```
94
+ */
56
95
  const printRelations = (type, options) => {
57
96
  const relations = {
58
97
  returnedBy: { section: "Returned By", getRelation: graphql_1.getRelationOfReturn },
package/dist/section.d.ts CHANGED
@@ -1,5 +1,50 @@
1
+ /**
2
+ * Module responsible for generating Markdown sections for GraphQL schema documentation.
3
+ * Handles the printing of section items, metadata, and structured documentation content.
4
+ * @module section
5
+ */
1
6
  import type { MDXString, PrintTypeOptions } from "@graphql-markdown/types";
7
+ /**
8
+ * Prints a single section item with its associated metadata.
9
+ *
10
+ * @param type - The GraphQL type or field to print
11
+ * @param options - Configuration options for printing
12
+ * @returns Formatted MDX string containing the section item
13
+ *
14
+ * @template T - Type of the GraphQL element being printed
15
+ */
2
16
  export declare const printSectionItem: <T>(type: T, options: PrintTypeOptions) => MDXString | string;
17
+ /**
18
+ * Prints an array of section items with consistent formatting.
19
+ *
20
+ * @param values - Single value or array of values to print as section items
21
+ * @param options - Configuration options for printing
22
+ * @returns Formatted MDX string containing all section items
23
+ *
24
+ * @template V - Type of the values being printed
25
+ */
3
26
  export declare const printSectionItems: <V>(values: V | V[], options: PrintTypeOptions) => MDXString | string;
27
+ /**
28
+ * Prints a complete section with title and content.
29
+ *
30
+ * @param values - Array of values to include in the section
31
+ * @param section - Section title/header
32
+ * @param options - Configuration options for printing
33
+ * @returns Formatted MDX string containing the complete section
34
+ *
35
+ * @template V - Type of the values being printed
36
+ */
4
37
  export declare const printSection: <V>(values: V[] | readonly V[], section: string, options: PrintTypeOptions) => MDXString | string;
38
+ /**
39
+ * Prints a metadata section with special handling for deprecated items.
40
+ *
41
+ * @param type - The parent type containing the metadata
42
+ * @param values - Values to include in the metadata section
43
+ * @param section - Section title/header
44
+ * @param options - Configuration options for printing
45
+ * @returns Formatted MDX string containing the metadata section
46
+ *
47
+ * @template T - Type of the parent element
48
+ * @template V - Type of the values being printed
49
+ */
5
50
  export declare const printMetadataSection: <T, V>(type: T, values: V | V[] | readonly V[], section: string, options: PrintTypeOptions) => MDXString | string;
package/dist/section.js CHANGED
@@ -1,4 +1,9 @@
1
1
  "use strict";
2
+ /**
3
+ * Module responsible for generating Markdown sections for GraphQL schema documentation.
4
+ * Handles the printing of section items, metadata, and structured documentation content.
5
+ * @module section
6
+ */
2
7
  Object.defineProperty(exports, "__esModule", { value: true });
3
8
  exports.printMetadataSection = exports.printSection = exports.printSectionItems = exports.printSectionItem = void 0;
4
9
  const graphql_1 = require("@graphql-markdown/graphql");
@@ -8,6 +13,15 @@ const link_1 = require("./link");
8
13
  const directive_1 = require("./directive");
9
14
  const strings_1 = require("./const/strings");
10
15
  const options_1 = require("./const/options");
16
+ /**
17
+ * Prints a single section item with its associated metadata.
18
+ *
19
+ * @param type - The GraphQL type or field to print
20
+ * @param options - Configuration options for printing
21
+ * @returns Formatted MDX string containing the section item
22
+ *
23
+ * @template T - Type of the GraphQL element being printed
24
+ */
11
25
  const printSectionItem = (type, options) => {
12
26
  const level = "level" in options && typeof options.level === "number" ? options.level : 4;
13
27
  if (!(0, link_1.hasPrintableDirective)(type, options)) {
@@ -38,6 +52,15 @@ const printSectionItem = (type, options) => {
38
52
  return section;
39
53
  };
40
54
  exports.printSectionItem = printSectionItem;
55
+ /**
56
+ * Prints an array of section items with consistent formatting.
57
+ *
58
+ * @param values - Single value or array of values to print as section items
59
+ * @param options - Configuration options for printing
60
+ * @returns Formatted MDX string containing all section items
61
+ *
62
+ * @template V - Type of the values being printed
63
+ */
41
64
  const printSectionItems = (values, options) => {
42
65
  if (!Array.isArray(values) || values.length === 0) {
43
66
  return "";
@@ -54,6 +77,16 @@ const printSectionItems = (values, options) => {
54
77
  .join(strings_1.MARKDOWN_EOP);
55
78
  };
56
79
  exports.printSectionItems = printSectionItems;
80
+ /**
81
+ * Prints a complete section with title and content.
82
+ *
83
+ * @param values - Array of values to include in the section
84
+ * @param section - Section title/header
85
+ * @param options - Configuration options for printing
86
+ * @returns Formatted MDX string containing the complete section
87
+ *
88
+ * @template V - Type of the values being printed
89
+ */
57
90
  const printSection = (values, section, options) => {
58
91
  if (!Array.isArray(values) || values.length === 0) {
59
92
  return "";
@@ -77,6 +110,18 @@ const printSection = (values, section, options) => {
77
110
  return `${options_1.SectionLevels.LEVEL.repeat(level)} ${section}${openSection}${items}${closeSection}`;
78
111
  };
79
112
  exports.printSection = printSection;
113
+ /**
114
+ * Prints a metadata section with special handling for deprecated items.
115
+ *
116
+ * @param type - The parent type containing the metadata
117
+ * @param values - Values to include in the metadata section
118
+ * @param section - Section title/header
119
+ * @param options - Configuration options for printing
120
+ * @returns Formatted MDX string containing the metadata section
121
+ *
122
+ * @template T - Type of the parent element
123
+ * @template V - Type of the values being printed
124
+ */
80
125
  const printMetadataSection = (type, values, section, options) => {
81
126
  if (typeof type !== "object" ||
82
127
  type === null ||
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.12.0",
8
+ "version": "1.12.2",
9
9
  "license": "MIT",
10
10
  "repository": {
11
11
  "type": "git",
@@ -56,11 +56,11 @@
56
56
  "docs": "typedoc"
57
57
  },
58
58
  "dependencies": {
59
- "@graphql-markdown/graphql": "^1.1.6",
60
- "@graphql-markdown/utils": "^1.8.0"
59
+ "@graphql-markdown/graphql": "^1.1.8",
60
+ "@graphql-markdown/utils": "^1.9.0"
61
61
  },
62
62
  "devDependencies": {
63
- "@graphql-markdown/types": "^1.7.0"
63
+ "@graphql-markdown/types": "^1.8.0"
64
64
  },
65
65
  "resolutions": {
66
66
  "micromatch": "4.0.8"