@graphql-markdown/core 1.14.0 → 1.15.1

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/renderer.js CHANGED
@@ -6,18 +6,108 @@ const graphql_1 = require("@graphql-markdown/graphql");
6
6
  const utils_1 = require("@graphql-markdown/utils");
7
7
  const logger_1 = require("@graphql-markdown/logger");
8
8
  const config_1 = require("./config");
9
+ /**
10
+ * Constant representing the string literal for deprecated entities.
11
+ * Used for grouping deprecated schema entities when the deprecated option is set to "group".
12
+ *
13
+ * @example
14
+ * ```typescript
15
+ * // When using the deprecated grouping option
16
+ * if (isDeprecated(type)) {
17
+ * const groupName = DEPRECATED;
18
+ * // Handle deprecated type
19
+ * }
20
+ * ```
21
+ */
9
22
  const DEPRECATED = "deprecated";
10
- const CATEGORY_YAML = "_category_.yml";
11
- const CATEGORY_STYLE_CLASS = "graphql-markdown-api-section";
23
+ /**
24
+ * CSS class names used for styling different categories in the generated documentation.
25
+ * These are applied to the generated index metafiles for different section types.
26
+ *
27
+ * @example
28
+ * ```typescript
29
+ * // When generating API section metafiles
30
+ * await generateIndexMetafile(dirPath, typeCat, {
31
+ * styleClass: CATEGORY_STYLE_CLASS.API
32
+ * });
33
+ * ```
34
+ */
35
+ var CATEGORY_STYLE_CLASS;
36
+ (function (CATEGORY_STYLE_CLASS) {
37
+ /**
38
+ * CSS class applied to API sections (operations)
39
+ */
40
+ CATEGORY_STYLE_CLASS["API"] = "graphql-markdown-api-section";
41
+ /**
42
+ * CSS class applied to deprecated entity sections
43
+ */
44
+ CATEGORY_STYLE_CLASS["DEPRECATED"] = "graphql-markdown-deprecated-section";
45
+ })(CATEGORY_STYLE_CLASS || (CATEGORY_STYLE_CLASS = {}));
46
+ /**
47
+ * Enum defining sidebar position values for ordering categories in the documentation sidebar.
48
+ * Used to control the relative position of categories in the navigation.
49
+ *
50
+ * @example
51
+ * ```typescript
52
+ * // Position deprecated entities at the end of the sidebar
53
+ * await generateIndexMetafile(dirPath, DEPRECATED, {
54
+ * sidebarPosition: SidebarPosition.LAST
55
+ * });
56
+ * ```
57
+ */
12
58
  var SidebarPosition;
13
59
  (function (SidebarPosition) {
60
+ /**
61
+ * Position at the beginning of the sidebar
62
+ */
14
63
  SidebarPosition[SidebarPosition["FIRST"] = 1] = "FIRST";
64
+ /**
65
+ * Position at the end of the sidebar
66
+ */
15
67
  SidebarPosition[SidebarPosition["LAST"] = 999] = "LAST";
16
68
  })(SidebarPosition || (SidebarPosition = {}));
69
+ /**
70
+ * Default group names for API types and non-API types.
71
+ * This constant provides the base folder structure for organizing GraphQL schema entities.
72
+ * Can be overridden via ApiGroupOverrideType in configuration.
73
+ *
74
+ * @property operations Folder name for GraphQL operations (queries, mutations, subscriptions)
75
+ * @property types Folder name for GraphQL type definitions
76
+ * @useDeclaredType
77
+ *
78
+ * @example
79
+ * ```typescript
80
+ * // Default structure
81
+ * const defaultGroups = API_GROUPS;
82
+ * // { operations: "operations", types: "types" }
83
+ *
84
+ * // With custom override
85
+ * const customGroups = { ...API_GROUPS, operations: "queries-and-mutations" };
86
+ * ```
87
+ *
88
+ * @see {@link getApiGroupFolder} For usage with type categorization
89
+ */
17
90
  exports.API_GROUPS = {
18
91
  operations: "operations",
19
92
  types: "types",
20
93
  };
94
+ /**
95
+ * Determines the appropriate folder for a GraphQL schema entity based on its type.
96
+ *
97
+ * @param type - The GraphQL schema entity to categorize
98
+ * @param groups - Optional custom group naming configuration
99
+ * @returns The folder name where the entity should be placed
100
+ * @useDeclaredType
101
+ *
102
+ * @example
103
+ * ```typescript
104
+ * // With default groups
105
+ * const folder = getApiGroupFolder(queryType); // Returns "operations"
106
+ *
107
+ * // With custom groups
108
+ * const folder = getApiGroupFolder(objectType, { operations: "queries" }); // Returns appropriate folder
109
+ * ```
110
+ */
21
111
  const getApiGroupFolder = (type, groups) => {
22
112
  let folderNames = exports.API_GROUPS;
23
113
  if (groups && typeof groups === "object") {
@@ -26,47 +116,119 @@ const getApiGroupFolder = (type, groups) => {
26
116
  return (0, graphql_1.isApiType)(type) ? folderNames.operations : folderNames.types;
27
117
  };
28
118
  exports.getApiGroupFolder = getApiGroupFolder;
119
+ /**
120
+ * Type guard function that checks if the provided options include a specific hierarchy configuration.
121
+ *
122
+ * @param options - The renderer options to check
123
+ * @param hierarchy - The hierarchy type to check for
124
+ * @returns True if the options contain the specified hierarchy configuration
125
+ * @useDeclaredType
126
+ *
127
+ * @example
128
+ * ```typescript
129
+ * if (isHierarchy(options, TypeHierarchy.FLAT)) {
130
+ * // Handle flat hierarchy structure
131
+ * }
132
+ * ```
133
+ */
29
134
  const isHierarchy = (options, hierarchy) => {
30
135
  return (options?.hierarchy?.[hierarchy] && true);
31
136
  };
137
+ const isPath = (path) => {
138
+ return typeof path === "string" && path !== "";
139
+ };
140
+ /**
141
+ * Core renderer class responsible for generating documentation files from GraphQL schema entities.
142
+ * Handles the conversion of schema types to markdown/MDX documentation with proper organization.
143
+ * @useDeclaredType
144
+ * @example
145
+ */
32
146
  class Renderer {
33
147
  group;
34
148
  outputDir;
35
149
  baseURL;
36
150
  prettify;
37
151
  options;
38
- hasMDXSupport;
152
+ mdxModule;
153
+ mdxModuleIndexFileSupport;
39
154
  printer;
40
- constructor(printer, outputDir, baseURL, group, prettify, docOptions, mdx = false) {
155
+ /**
156
+ * Creates a new Renderer instance.
157
+ *
158
+ * @param printer - The printer instance used to convert GraphQL types to markdown
159
+ * @param outputDir - Directory where documentation will be generated
160
+ * @param baseURL - Base URL for the documentation
161
+ * @param group - Optional grouping configuration for schema entities
162
+ * @param prettify - Whether to format the generated markdown
163
+ * @param docOptions - Additional documentation options
164
+ * @param mdxModule - Optional MDX module for enhanced documentation features
165
+ * @example
166
+ */
167
+ constructor(printer, outputDir, baseURL, group, prettify, docOptions, mdxModule) {
41
168
  this.printer = printer;
42
169
  this.group = group;
43
170
  this.outputDir = outputDir;
44
171
  this.baseURL = baseURL;
45
172
  this.prettify = prettify;
46
173
  this.options = docOptions;
47
- this.hasMDXSupport = mdx;
174
+ this.mdxModule = mdxModule;
175
+ this.mdxModuleIndexFileSupport = this.hasMDXIndexFileSupport(mdxModule);
176
+ }
177
+ /**
178
+ * Checks if the provided module supports MDX index file generation.
179
+ *
180
+ * @param module - The module to check for MDX support
181
+ * @returns True if the module supports index metafile generation
182
+ * @useDeclaredType
183
+ * @example
184
+ */
185
+ hasMDXIndexFileSupport(module = this.mdxModule) {
186
+ return !!(module &&
187
+ typeof module === "object" &&
188
+ "generateIndexMetafile" in module &&
189
+ typeof module.generateIndexMetafile === "function");
48
190
  }
49
- async generateCategoryMetafile(category, dirPath, sidebarPosition, styleClass, options = {
191
+ /**
192
+ * Generates an index metafile for a category directory if MDX support is available.
193
+ *
194
+ * @param dirPath - The directory path where the index should be created
195
+ * @param category - The category name
196
+ * @param options - Configuration options for the index
197
+ * @returns Promise that resolves when the index is generated
198
+ * @useDeclaredType
199
+ *
200
+ * @example
201
+ * ```typescript
202
+ * await renderer.generateIndexMetafile('docs/types', 'Types', {
203
+ * collapsible: true,
204
+ * collapsed: false
205
+ * });
206
+ * ```
207
+ */
208
+ async generateIndexMetafile(dirPath, category, options = {
50
209
  collapsible: true,
51
210
  collapsed: true,
52
211
  }) {
53
- const filePath = (0, node_path_1.join)(dirPath, CATEGORY_YAML);
54
- if (await (0, utils_1.fileExists)(filePath)) {
55
- return;
212
+ if (this.mdxModuleIndexFileSupport) {
213
+ await this.mdxModule.generateIndexMetafile(dirPath, category, { ...options, index: this.options?.index });
56
214
  }
57
- await (0, utils_1.ensureDir)(dirPath);
58
- const label = (0, utils_1.startCase)(category);
59
- const link = this.options && this.options.index !== true
60
- ? "null"
61
- : `\n type: generated-index\n title: '${label} overview'`;
62
- const className = typeof styleClass === "string" ? `className: ${styleClass}\n` : "";
63
- const position = typeof sidebarPosition === "number"
64
- ? sidebarPosition
65
- : SidebarPosition.FIRST;
66
- await (0, utils_1.saveFile)(filePath, `label: ${label}\nposition: ${position}\n${className}link: ${link}\ncollapsible: ${options.collapsible}\ncollapsed: ${options.collapsed}\n`);
67
215
  }
216
+ /**
217
+ * Generates the directory path and metafiles for a specific schema entity type.
218
+ * Creates the appropriate directory structure based on configuration options.
219
+ *
220
+ * @param type - The schema entity type
221
+ * @param name - The name of the schema entity
222
+ * @param rootTypeName - The root type name this entity belongs to
223
+ * @returns The generated directory path
224
+ * @useDeclaredType
225
+ * @example
226
+ */
68
227
  async generateCategoryMetafileType(type, name, rootTypeName) {
69
228
  let dirPath = this.outputDir;
229
+ if (!isPath(dirPath)) {
230
+ throw new Error("Output directory is empty or not specified");
231
+ }
70
232
  if (isHierarchy(this.options, config_1.TypeHierarchy.FLAT)) {
71
233
  return dirPath;
72
234
  }
@@ -76,22 +238,39 @@ class Renderer {
76
238
  if (useApiGroup) {
77
239
  const typeCat = (0, exports.getApiGroupFolder)(type, useApiGroup);
78
240
  dirPath = (0, node_path_1.join)(dirPath, (0, utils_1.slugify)(typeCat));
79
- await this.generateCategoryMetafile(typeCat, dirPath, undefined, CATEGORY_STYLE_CLASS, { collapsible: false, collapsed: false });
241
+ await this.generateIndexMetafile(dirPath, typeCat, {
242
+ collapsible: false,
243
+ collapsed: false,
244
+ styleClass: CATEGORY_STYLE_CLASS.API,
245
+ });
80
246
  }
81
247
  if (this.options?.deprecated === "group" && (0, graphql_1.isDeprecated)(type)) {
82
248
  dirPath = (0, node_path_1.join)(dirPath, (0, utils_1.slugify)(DEPRECATED));
83
- await this.generateCategoryMetafile(DEPRECATED, dirPath, SidebarPosition.LAST, DEPRECATED);
249
+ await this.generateIndexMetafile(dirPath, DEPRECATED, {
250
+ sidebarPosition: SidebarPosition.LAST,
251
+ styleClass: CATEGORY_STYLE_CLASS.DEPRECATED,
252
+ });
84
253
  }
85
254
  if (this.group &&
86
255
  rootTypeName in this.group &&
87
256
  name in this.group[rootTypeName]) {
88
- dirPath = (0, node_path_1.join)(dirPath, (0, utils_1.slugify)(this.group[rootTypeName][name] ?? ""));
89
- await this.generateCategoryMetafile(this.group[rootTypeName][name] ?? "", dirPath);
257
+ const rootGroup = this.group[rootTypeName][name] ?? "";
258
+ dirPath = (0, node_path_1.join)(dirPath, (0, utils_1.slugify)(rootGroup));
259
+ await this.generateIndexMetafile(dirPath, rootGroup);
90
260
  }
91
261
  dirPath = (0, node_path_1.join)(dirPath, (0, utils_1.slugify)(rootTypeName));
92
- await this.generateCategoryMetafile(rootTypeName, dirPath);
262
+ await this.generateIndexMetafile(dirPath, rootTypeName);
93
263
  return dirPath;
94
264
  }
265
+ /**
266
+ * Renders all types within a root type category (e.g., all Query types).
267
+ *
268
+ * @param rootTypeName - The name of the root type (e.g., "Query", "Mutation")
269
+ * @param type - The type object containing all entities to render
270
+ * @returns Array of rendered categories or undefined
271
+ * @useDeclaredType
272
+ * @example
273
+ */
95
274
  async renderRootTypes(rootTypeName, type) {
96
275
  if (typeof type !== "object" || type === null) {
97
276
  return undefined;
@@ -109,16 +288,29 @@ class Renderer {
109
288
  return typeof res !== "undefined";
110
289
  }));
111
290
  }
291
+ /**
292
+ * Renders documentation for a specific type entity and saves it to a file.
293
+ *
294
+ * @param dirPath - The directory path where the file should be saved
295
+ * @param name - The name of the type entity
296
+ * @param type - The type entity to render
297
+ * @returns The category information for the rendered entity or undefined
298
+ * @useDeclaredType
299
+ * @example
300
+ */
112
301
  async renderTypeEntities(dirPath, name, type) {
302
+ if (!isPath(dirPath)) {
303
+ throw new Error("Output directory is empty or not specified");
304
+ }
113
305
  const PageRegex = /(?<category>[A-Za-z0-9-]+)[\\/]+(?<pageId>[A-Za-z0-9-]+).mdx?$/;
114
306
  const PageRegexFlat = /(?<pageId>[A-Za-z0-9-]+).mdx?$/;
115
- const extension = this.hasMDXSupport ? "mdx" : "md";
307
+ const extension = this.mdxModule ? "mdx" : "md";
116
308
  const fileName = (0, utils_1.slugify)(name);
117
309
  const filePath = (0, node_path_1.join)((0, node_path_1.normalize)(dirPath), `${fileName}.${extension}`);
118
310
  let content;
119
311
  try {
120
312
  content = this.printer.printType(fileName, type, this.options);
121
- if (typeof content !== "string") {
313
+ if (typeof content !== "string" || content === "") {
122
314
  return undefined;
123
315
  }
124
316
  }
@@ -145,22 +337,69 @@ class Renderer {
145
337
  slug,
146
338
  };
147
339
  }
340
+ /**
341
+ * Renders the homepage for the documentation from a template file.
342
+ * Replaces placeholders in the template with actual values.
343
+ *
344
+ * @param homepageLocation - Path to the homepage template file
345
+ * @returns Promise that resolves when the homepage is rendered
346
+ * @useDeclaredType
347
+ * @example
348
+ */
148
349
  async renderHomepage(homepageLocation) {
350
+ if (typeof homepageLocation !== "string") {
351
+ (0, logger_1.log)("Homepage location is not a valid string", logger_1.LogLevel.warn);
352
+ return;
353
+ }
354
+ if (!isPath(this.outputDir)) {
355
+ throw new Error("Output directory is empty or not specified");
356
+ }
149
357
  const homePage = (0, node_path_1.basename)(homepageLocation);
150
358
  const destLocation = (0, node_path_1.join)(this.outputDir, homePage);
151
359
  const slug = utils_1.pathUrl.resolve("/", this.baseURL);
152
- await (0, utils_1.copyFile)(homepageLocation, destLocation);
153
- const template = await (0, utils_1.readFile)(destLocation);
154
- const data = template
155
- .toString()
156
- .replace(/##baseURL##/gm, slug)
157
- .replace(/##generated-date-time##/gm, new Date().toLocaleString());
158
- await (0, utils_1.saveFile)(destLocation, data);
360
+ try {
361
+ await (0, utils_1.copyFile)(homepageLocation, destLocation);
362
+ const template = await (0, utils_1.readFile)(destLocation);
363
+ const data = template
364
+ .toString()
365
+ .replace(/##baseURL##/gm, slug)
366
+ .replace(/##generated-date-time##/gm, new Date().toLocaleString());
367
+ await (0, utils_1.saveFile)(destLocation, data, this.prettify ? utils_1.prettifyMarkdown : undefined);
368
+ }
369
+ catch (error) {
370
+ (0, logger_1.log)(`An error occurred while processing the homepage ${homepageLocation}: ${error}`, logger_1.LogLevel.warn);
371
+ }
159
372
  }
160
373
  }
161
374
  exports.Renderer = Renderer;
162
- const getRenderer = async (printer, outputDir, baseURL, group, prettify, docOptions, mdx = false) => {
375
+ /**
376
+ * Factory function to create and initialize a Renderer instance.
377
+ * Creates the output directory and returns a configured renderer.
378
+ *
379
+ * @param printer - The printer instance to use for rendering types
380
+ * @param outputDir - The output directory for generated documentation
381
+ * @param baseURL - The base URL for the documentation
382
+ * @param group - Optional grouping configuration
383
+ * @param prettify - Whether to prettify the output markdown
384
+ * @param docOptions - Additional documentation options
385
+ * @param mdxModule - Optional MDX module for enhanced features
386
+ * @returns A configured Renderer instance
387
+ * @useDeclaredType
388
+ *
389
+ * @example
390
+ * ```typescript
391
+ * const renderer = await getRenderer(
392
+ * myPrinter,
393
+ * './docs',
394
+ * '/api',
395
+ * groupConfig,
396
+ * true,
397
+ * { force: true, index: true }
398
+ * );
399
+ * ```
400
+ */
401
+ const getRenderer = async (printer, outputDir, baseURL, group, prettify, docOptions, mdxModule) => {
163
402
  await (0, utils_1.ensureDir)(outputDir, { forceEmpty: docOptions?.force });
164
- return new Renderer(printer, outputDir, baseURL, group, prettify, docOptions, mdx);
403
+ return new Renderer(printer, outputDir, baseURL, group, prettify, docOptions, mdxModule);
165
404
  };
166
405
  exports.getRenderer = getRenderer;
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.1",
9
9
  "license": "MIT",
10
10
  "repository": {
11
11
  "type": "git",
@@ -60,21 +60,22 @@
60
60
  "postpack": "pinst --enable",
61
61
  "stryker": "stryker run",
62
62
  "clean": "rm -rf ./dist",
63
- "docs": "typedoc"
63
+ "docs": "typedoc",
64
+ "suggest:tests": "ts-node ../../scripts/test-suggestions.ts"
64
65
  },
65
66
  "dependencies": {
66
- "@graphql-markdown/graphql": "^1.1.5",
67
+ "@graphql-markdown/graphql": "^1.1.7",
67
68
  "@graphql-markdown/logger": "^1.0.5",
68
- "@graphql-markdown/utils": "^1.7.1"
69
+ "@graphql-markdown/utils": "^1.8.1"
69
70
  },
70
71
  "peerDependencies": {
71
- "@graphql-markdown/diff": "^1.1.9",
72
- "@graphql-markdown/helpers": "^1.0.8",
73
- "@graphql-markdown/printer-legacy": "^1.11.0",
72
+ "@graphql-markdown/diff": "^1.1.11",
73
+ "@graphql-markdown/helpers": "^1.0.10",
74
+ "@graphql-markdown/printer-legacy": "^1.12.1",
74
75
  "graphql-config": "^5.1.0"
75
76
  },
76
77
  "devDependencies": {
77
- "@graphql-markdown/types": "^1.6.0"
78
+ "@graphql-markdown/types": "^1.7.0"
78
79
  },
79
80
  "peerDependenciesMeta": {
80
81
  "@graphql-markdown/printer-legacy": {