@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/config.d.ts +350 -0
- package/dist/config.js +365 -6
- package/dist/diff.d.ts +51 -0
- package/dist/diff.js +51 -0
- package/dist/generator.d.ts +22 -0
- package/dist/generator.js +24 -0
- package/dist/graphql-config.d.ts +85 -2
- package/dist/graphql-config.js +68 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +3 -0
- package/dist/printer.d.ts +50 -0
- package/dist/printer.js +44 -0
- package/dist/renderer.d.ts +168 -1
- package/dist/renderer.js +238 -8
- package/package.json +9 -8
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
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
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.
|
|
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.
|
|
67
|
+
"@graphql-markdown/graphql": "^1.1.8",
|
|
67
68
|
"@graphql-markdown/logger": "^1.0.5",
|
|
68
|
-
"@graphql-markdown/utils": "^1.
|
|
69
|
+
"@graphql-markdown/utils": "^1.9.0"
|
|
69
70
|
},
|
|
70
71
|
"peerDependencies": {
|
|
71
|
-
"@graphql-markdown/diff": "^1.1.
|
|
72
|
-
"@graphql-markdown/helpers": "^1.0.
|
|
73
|
-
"@graphql-markdown/printer-legacy": "^1.12.
|
|
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.
|
|
78
|
+
"@graphql-markdown/types": "^1.8.0"
|
|
78
79
|
},
|
|
79
80
|
"peerDependenciesMeta": {
|
|
80
81
|
"@graphql-markdown/printer-legacy": {
|