@graphql-markdown/core 1.15.0 → 1.16.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/renderer.js CHANGED
@@ -6,21 +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";
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
+ */
10
35
  var CATEGORY_STYLE_CLASS;
11
36
  (function (CATEGORY_STYLE_CLASS) {
37
+ /**
38
+ * CSS class applied to API sections (operations)
39
+ */
12
40
  CATEGORY_STYLE_CLASS["API"] = "graphql-markdown-api-section";
41
+ /**
42
+ * CSS class applied to deprecated entity sections
43
+ */
13
44
  CATEGORY_STYLE_CLASS["DEPRECATED"] = "graphql-markdown-deprecated-section";
14
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
+ */
15
58
  var SidebarPosition;
16
59
  (function (SidebarPosition) {
60
+ /**
61
+ * Position at the beginning of the sidebar
62
+ */
17
63
  SidebarPosition[SidebarPosition["FIRST"] = 1] = "FIRST";
64
+ /**
65
+ * Position at the end of the sidebar
66
+ */
18
67
  SidebarPosition[SidebarPosition["LAST"] = 999] = "LAST";
19
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
+ */
20
90
  exports.API_GROUPS = {
21
91
  operations: "operations",
22
92
  types: "types",
23
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
+ */
24
111
  const getApiGroupFolder = (type, groups) => {
25
112
  let folderNames = exports.API_GROUPS;
26
113
  if (groups && typeof groups === "object") {
@@ -29,9 +116,33 @@ const getApiGroupFolder = (type, groups) => {
29
116
  return (0, graphql_1.isApiType)(type) ? folderNames.operations : folderNames.types;
30
117
  };
31
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
+ */
32
134
  const isHierarchy = (options, hierarchy) => {
33
135
  return (options?.hierarchy?.[hierarchy] && true);
34
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
+ */
35
146
  class Renderer {
36
147
  group;
37
148
  outputDir;
@@ -41,6 +152,18 @@ class Renderer {
41
152
  mdxModule;
42
153
  mdxModuleIndexFileSupport;
43
154
  printer;
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
+ */
44
167
  constructor(printer, outputDir, baseURL, group, prettify, docOptions, mdxModule) {
45
168
  this.printer = printer;
46
169
  this.group = group;
@@ -51,12 +174,37 @@ class Renderer {
51
174
  this.mdxModule = mdxModule;
52
175
  this.mdxModuleIndexFileSupport = this.hasMDXIndexFileSupport(mdxModule);
53
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
+ */
54
185
  hasMDXIndexFileSupport(module = this.mdxModule) {
55
186
  return !!(module &&
56
187
  typeof module === "object" &&
57
188
  "generateIndexMetafile" in module &&
58
189
  typeof module.generateIndexMetafile === "function");
59
190
  }
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
+ */
60
208
  async generateIndexMetafile(dirPath, category, options = {
61
209
  collapsible: true,
62
210
  collapsed: true,
@@ -65,8 +213,22 @@ class Renderer {
65
213
  await this.mdxModule.generateIndexMetafile(dirPath, category, { ...options, index: this.options?.index });
66
214
  }
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
  }
@@ -100,6 +262,15 @@ class Renderer {
100
262
  await this.generateIndexMetafile(dirPath, rootTypeName);
101
263
  return dirPath;
102
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
+ */
103
274
  async renderRootTypes(rootTypeName, type) {
104
275
  if (typeof type !== "object" || type === null) {
105
276
  return undefined;
@@ -117,7 +288,20 @@ class Renderer {
117
288
  return typeof res !== "undefined";
118
289
  }));
119
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
+ */
120
301
  async renderTypeEntities(dirPath, name, type) {
302
+ if (!isPath(dirPath)) {
303
+ throw new Error("Output directory is empty or not specified");
304
+ }
121
305
  const PageRegex = /(?<category>[A-Za-z0-9-]+)[\\/]+(?<pageId>[A-Za-z0-9-]+).mdx?$/;
122
306
  const PageRegexFlat = /(?<pageId>[A-Za-z0-9-]+).mdx?$/;
123
307
  const extension = this.mdxModule ? "mdx" : "md";
@@ -126,7 +310,7 @@ class Renderer {
126
310
  let content;
127
311
  try {
128
312
  content = this.printer.printType(fileName, type, this.options);
129
- if (typeof content !== "string") {
313
+ if (typeof content !== "string" || content === "") {
130
314
  return undefined;
131
315
  }
132
316
  }
@@ -153,20 +337,66 @@ class Renderer {
153
337
  slug,
154
338
  };
155
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
+ */
156
349
  async renderHomepage(homepageLocation) {
350
+ if (typeof homepageLocation !== "string") {
351
+ return;
352
+ }
353
+ if (!isPath(this.outputDir)) {
354
+ throw new Error("Output directory is empty or not specified");
355
+ }
157
356
  const homePage = (0, node_path_1.basename)(homepageLocation);
158
357
  const destLocation = (0, node_path_1.join)(this.outputDir, homePage);
159
358
  const slug = utils_1.pathUrl.resolve("/", this.baseURL);
160
- await (0, utils_1.copyFile)(homepageLocation, destLocation);
161
- const template = await (0, utils_1.readFile)(destLocation);
162
- const data = template
163
- .toString()
164
- .replace(/##baseURL##/gm, slug)
165
- .replace(/##generated-date-time##/gm, new Date().toLocaleString());
166
- await (0, utils_1.saveFile)(destLocation, data);
359
+ try {
360
+ await (0, utils_1.copyFile)(homepageLocation, destLocation);
361
+ const template = await (0, utils_1.readFile)(destLocation);
362
+ const data = template
363
+ .toString()
364
+ .replace(/##baseURL##/gm, slug)
365
+ .replace(/##generated-date-time##/gm, new Date().toLocaleString());
366
+ await (0, utils_1.saveFile)(destLocation, data, this.prettify ? utils_1.prettifyMarkdown : undefined);
367
+ }
368
+ catch (error) {
369
+ (0, logger_1.log)(`An error occurred while processing the homepage ${homepageLocation}: ${error}`, logger_1.LogLevel.warn);
370
+ }
167
371
  }
168
372
  }
169
373
  exports.Renderer = Renderer;
374
+ /**
375
+ * Factory function to create and initialize a Renderer instance.
376
+ * Creates the output directory and returns a configured renderer.
377
+ *
378
+ * @param printer - The printer instance to use for rendering types
379
+ * @param outputDir - The output directory for generated documentation
380
+ * @param baseURL - The base URL for the documentation
381
+ * @param group - Optional grouping configuration
382
+ * @param prettify - Whether to prettify the output markdown
383
+ * @param docOptions - Additional documentation options
384
+ * @param mdxModule - Optional MDX module for enhanced features
385
+ * @returns A configured Renderer instance
386
+ * @useDeclaredType
387
+ *
388
+ * @example
389
+ * ```typescript
390
+ * const renderer = await getRenderer(
391
+ * myPrinter,
392
+ * './docs',
393
+ * '/api',
394
+ * groupConfig,
395
+ * true,
396
+ * { force: true, index: true }
397
+ * );
398
+ * ```
399
+ */
170
400
  const getRenderer = async (printer, outputDir, baseURL, group, prettify, docOptions, mdxModule) => {
171
401
  await (0, utils_1.ensureDir)(outputDir, { forceEmpty: docOptions?.force });
172
402
  return new Renderer(printer, outputDir, baseURL, group, prettify, docOptions, mdxModule);
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.15.0",
8
+ "version": "1.16.0",
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.6",
67
+ "@graphql-markdown/graphql": "^1.1.8",
67
68
  "@graphql-markdown/logger": "^1.0.5",
68
- "@graphql-markdown/utils": "^1.8.0"
69
+ "@graphql-markdown/utils": "^1.9.0"
69
70
  },
70
71
  "peerDependencies": {
71
- "@graphql-markdown/diff": "^1.1.10",
72
- "@graphql-markdown/helpers": "^1.0.9",
73
- "@graphql-markdown/printer-legacy": "^1.12.0",
72
+ "@graphql-markdown/diff": "^1.1.12",
73
+ "@graphql-markdown/helpers": "^1.0.11",
74
+ "@graphql-markdown/printer-legacy": "^1.12.2",
74
75
  "graphql-config": "^5.1.0"
75
76
  },
76
77
  "devDependencies": {
77
- "@graphql-markdown/types": "^1.7.0"
78
+ "@graphql-markdown/types": "^1.8.0"
78
79
  },
79
80
  "peerDependenciesMeta": {
80
81
  "@graphql-markdown/printer-legacy": {