@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/config.js
CHANGED
|
@@ -1,11 +1,38 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Configuration management for GraphQL Markdown.
|
|
4
|
+
*
|
|
5
|
+
* This module handles all aspects of configuration including:
|
|
6
|
+
* - Loading and merging configuration from multiple sources
|
|
7
|
+
* - Validating configuration values
|
|
8
|
+
* - Providing defaults for missing options
|
|
9
|
+
* - Processing special configuration options (directives, deprecated items, etc)
|
|
10
|
+
*
|
|
11
|
+
* The configuration follows this precedence (highest to lowest):
|
|
12
|
+
* 1. CLI arguments
|
|
13
|
+
* 2. Config file options
|
|
14
|
+
* 3. GraphQL Config options
|
|
15
|
+
* 4. Default values
|
|
16
|
+
*
|
|
17
|
+
* @packageDocumentation
|
|
18
|
+
*/
|
|
2
19
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.buildConfig = exports.parseGroupByOption = exports.getPrintTypeOptions = exports.parseDeprecatedPrintTypeOptions = exports.getTypeHierarchyOption = exports.getDocOptions = exports.parseDeprecatedDocOptions = exports.getDiffMethod = exports.getCustomDirectives = exports.getVisibilityDirectives = exports.getSkipDocDirectives = exports.getOnlyDocDirectives = exports.getDocDirective = exports.DEFAULT_OPTIONS = exports.DEFAULT_HIERARCHY = exports.ASSET_HOMEPAGE_LOCATION = exports.PACKAGE_NAME = exports.DOCS_URL = exports.DeprecatedOption = exports.DiffMethod = exports.TypeHierarchy = void 0;
|
|
20
|
+
exports.buildConfig = exports.parseHomepageOption = exports.parseGroupByOption = exports.getPrintTypeOptions = exports.parseDeprecatedPrintTypeOptions = exports.getTypeHierarchyOption = exports.getDocOptions = exports.parseDeprecatedDocOptions = exports.getDiffMethod = exports.getCustomDirectives = exports.getVisibilityDirectives = exports.getSkipDocDirectives = exports.getOnlyDocDirectives = exports.getDocDirective = exports.DEFAULT_OPTIONS = exports.DEFAULT_HIERARCHY = exports.ASSET_HOMEPAGE_LOCATION = exports.PACKAGE_NAME = exports.DOCS_URL = exports.DeprecatedOption = exports.DiffMethod = exports.TypeHierarchy = void 0;
|
|
4
21
|
const node_path_1 = require("node:path");
|
|
5
22
|
const node_os_1 = require("node:os");
|
|
6
23
|
const graphql_config_1 = require("./graphql-config");
|
|
7
24
|
/**
|
|
25
|
+
* Type hierarchy options for organizing schema documentation.
|
|
26
|
+
*
|
|
27
|
+
* - API: Groups types by their role in the API (Query, Mutation, etc.)
|
|
28
|
+
* - ENTITY: Groups types by their entity relationships
|
|
29
|
+
* - FLAT: No grouping, all types in a flat structure
|
|
30
|
+
*
|
|
8
31
|
* @public
|
|
32
|
+
* @example
|
|
33
|
+
* ```typescript
|
|
34
|
+
* const hierarchy = TypeHierarchy.API;
|
|
35
|
+
* ```
|
|
9
36
|
*/
|
|
10
37
|
var TypeHierarchy;
|
|
11
38
|
(function (TypeHierarchy) {
|
|
@@ -14,7 +41,16 @@ var TypeHierarchy;
|
|
|
14
41
|
TypeHierarchy["FLAT"] = "flat";
|
|
15
42
|
})(TypeHierarchy || (exports.TypeHierarchy = TypeHierarchy = {}));
|
|
16
43
|
/**
|
|
44
|
+
* Diff methods used to determine how schema changes are processed.
|
|
45
|
+
*
|
|
46
|
+
* - NONE: No diffing is performed
|
|
47
|
+
* - FORCE: Force regeneration of documentation regardless of schema changes
|
|
48
|
+
*
|
|
17
49
|
* @public
|
|
50
|
+
* @example
|
|
51
|
+
* ```typescript
|
|
52
|
+
* const diffMethod = DiffMethod.FORCE;
|
|
53
|
+
* ```
|
|
18
54
|
*/
|
|
19
55
|
var DiffMethod;
|
|
20
56
|
(function (DiffMethod) {
|
|
@@ -22,7 +58,17 @@ var DiffMethod;
|
|
|
22
58
|
DiffMethod["FORCE"] = "FORCE";
|
|
23
59
|
})(DiffMethod || (exports.DiffMethod = DiffMethod = {}));
|
|
24
60
|
/**
|
|
61
|
+
* Options for handling deprecated items in the schema.
|
|
62
|
+
*
|
|
63
|
+
* - DEFAULT: Show deprecated items normally
|
|
64
|
+
* - GROUP: Group deprecated items separately
|
|
65
|
+
* - SKIP: Exclude deprecated items from documentation
|
|
66
|
+
*
|
|
25
67
|
* @public
|
|
68
|
+
* @example
|
|
69
|
+
* ```typescript
|
|
70
|
+
* const deprecatedHandling = DeprecatedOption.GROUP;
|
|
71
|
+
* ```
|
|
26
72
|
*/
|
|
27
73
|
var DeprecatedOption;
|
|
28
74
|
(function (DeprecatedOption) {
|
|
@@ -30,10 +76,33 @@ var DeprecatedOption;
|
|
|
30
76
|
DeprecatedOption["GROUP"] = "group";
|
|
31
77
|
DeprecatedOption["SKIP"] = "skip";
|
|
32
78
|
})(DeprecatedOption || (exports.DeprecatedOption = DeprecatedOption = {}));
|
|
79
|
+
/**
|
|
80
|
+
* Documentation website URL for reference in error messages and help text.
|
|
81
|
+
* @public
|
|
82
|
+
*/
|
|
33
83
|
exports.DOCS_URL = "https://graphql-markdown.dev/docs";
|
|
84
|
+
/**
|
|
85
|
+
* Default package name used for temporary directory creation and identification.
|
|
86
|
+
* @public
|
|
87
|
+
*/
|
|
34
88
|
exports.PACKAGE_NAME = "@graphql-markdown/docusaurus";
|
|
89
|
+
/**
|
|
90
|
+
* Location of the default homepage template.
|
|
91
|
+
* @public
|
|
92
|
+
*/
|
|
35
93
|
exports.ASSET_HOMEPAGE_LOCATION = (0, node_path_1.join)(__dirname, "..", "assets", "generated.md");
|
|
94
|
+
/**
|
|
95
|
+
* Default hierarchy configuration using the API hierarchy type.
|
|
96
|
+
* @public
|
|
97
|
+
*/
|
|
36
98
|
exports.DEFAULT_HIERARCHY = { [TypeHierarchy.API]: {} };
|
|
99
|
+
/**
|
|
100
|
+
* Default configuration options used when no user options are provided.
|
|
101
|
+
* These values serve as fallbacks for any missing configuration.
|
|
102
|
+
*
|
|
103
|
+
* @public
|
|
104
|
+
* @see {@link Options} for the complete configuration interface
|
|
105
|
+
*/
|
|
37
106
|
exports.DEFAULT_OPTIONS = {
|
|
38
107
|
id: "default",
|
|
39
108
|
baseURL: "schema",
|
|
@@ -65,6 +134,22 @@ exports.DEFAULT_OPTIONS = {
|
|
|
65
134
|
skipDocDirective: [],
|
|
66
135
|
onlyDocDirective: [],
|
|
67
136
|
};
|
|
137
|
+
/**
|
|
138
|
+
* Retrieves a directive name from a string by parsing and validating the format.
|
|
139
|
+
* Directive names should be prefixed with '\@' (e.g., '\@example').
|
|
140
|
+
*
|
|
141
|
+
* @param name - The directive name as a string, which should follow the format '\@directiveName'
|
|
142
|
+
* @returns The validated directive name without the '\@' prefix
|
|
143
|
+
* @throws Error if the directive name format is invalid
|
|
144
|
+
* @example
|
|
145
|
+
* ```typescript
|
|
146
|
+
* const directive = getDocDirective("@example");
|
|
147
|
+
* console.log(directive); // "example"
|
|
148
|
+
*
|
|
149
|
+
* // Invalid - will throw an error
|
|
150
|
+
* getDocDirective("example"); // Error: Invalid "example"
|
|
151
|
+
* ```
|
|
152
|
+
*/
|
|
68
153
|
const getDocDirective = (name) => {
|
|
69
154
|
const OPTION_REGEX = /^@(?<directive>\w+)$/;
|
|
70
155
|
if (typeof name !== "string" || !OPTION_REGEX.test(name)) {
|
|
@@ -74,6 +159,23 @@ const getDocDirective = (name) => {
|
|
|
74
159
|
return directive;
|
|
75
160
|
};
|
|
76
161
|
exports.getDocDirective = getDocDirective;
|
|
162
|
+
/**
|
|
163
|
+
* Retrieves the list of "only" directives from CLI and config options.
|
|
164
|
+
* These directives specify which schema elements should be included in the documentation.
|
|
165
|
+
*
|
|
166
|
+
* @param cliOpts - CLI options containing "only" directives
|
|
167
|
+
* @param configFileOpts - Config file options containing "onlyDocDirective"
|
|
168
|
+
* @returns An array of validated "only" directives (without '\@' prefix)
|
|
169
|
+
* @example
|
|
170
|
+
* ```typescript
|
|
171
|
+
* const cliOptions = { only: ["@example", "@internal"] };
|
|
172
|
+
* const configOptions = { onlyDocDirective: ["@auth"] };
|
|
173
|
+
*
|
|
174
|
+
* const onlyDirectives = getOnlyDocDirectives(cliOptions, configOptions);
|
|
175
|
+
* console.log(onlyDirectives); // ["example", "internal", "auth"]
|
|
176
|
+
* ```
|
|
177
|
+
* @see {@link getDocDirective} for directive name validation
|
|
178
|
+
*/
|
|
77
179
|
const getOnlyDocDirectives = (cliOpts, configFileOpts) => {
|
|
78
180
|
const directiveList = [].concat((cliOpts?.only ?? []), (configFileOpts?.onlyDocDirective ?? []));
|
|
79
181
|
const onlyDirectives = directiveList.map((directiveName) => {
|
|
@@ -82,13 +184,31 @@ const getOnlyDocDirectives = (cliOpts, configFileOpts) => {
|
|
|
82
184
|
return onlyDirectives;
|
|
83
185
|
};
|
|
84
186
|
exports.getOnlyDocDirectives = getOnlyDocDirectives;
|
|
187
|
+
/**
|
|
188
|
+
* Retrieves the list of "skip" directives from CLI and config options.
|
|
189
|
+
* These directives specify which schema elements should be excluded from the documentation.
|
|
190
|
+
* Additionally, if deprecated handling is set to SKIP, adds the "deprecated" directive.
|
|
191
|
+
*
|
|
192
|
+
* @param cliOpts - CLI options containing "skip" directives
|
|
193
|
+
* @param configFileOpts - Config file options containing "skipDocDirective" and potentially "printTypeOptions.deprecated"
|
|
194
|
+
* @returns An array of validated "skip" directives (without '\@' prefix)
|
|
195
|
+
* @example
|
|
196
|
+
* ```typescript
|
|
197
|
+
* const cliOptions = { skip: ["@internal"], deprecated: "skip" };
|
|
198
|
+
* const configOptions = { skipDocDirective: ["@auth"] };
|
|
199
|
+
*
|
|
200
|
+
* const skipDirectives = getSkipDocDirectives(cliOptions, configOptions);
|
|
201
|
+
* console.log(skipDirectives); // ["internal", "auth", "deprecated"]
|
|
202
|
+
* ```
|
|
203
|
+
* @see {@link getDocDirective} for directive name validation
|
|
204
|
+
* @see {@link DeprecatedOption} for deprecated handling options
|
|
205
|
+
*/
|
|
85
206
|
const getSkipDocDirectives = (cliOpts, configFileOpts) => {
|
|
86
207
|
const directiveList = [].concat((cliOpts?.skip ?? []), (configFileOpts?.skipDocDirective ?? []));
|
|
87
208
|
const skipDirectives = directiveList.map((directiveName) => {
|
|
88
209
|
return (0, exports.getDocDirective)(directiveName);
|
|
89
210
|
});
|
|
90
211
|
if ((configFileOpts &&
|
|
91
|
-
// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
|
|
92
212
|
configFileOpts.printTypeOptions?.deprecated === DeprecatedOption.SKIP) ||
|
|
93
213
|
(cliOpts && cliOpts.deprecated === DeprecatedOption.SKIP)) {
|
|
94
214
|
skipDirectives.push("deprecated");
|
|
@@ -96,6 +216,34 @@ const getSkipDocDirectives = (cliOpts, configFileOpts) => {
|
|
|
96
216
|
return skipDirectives;
|
|
97
217
|
};
|
|
98
218
|
exports.getSkipDocDirectives = getSkipDocDirectives;
|
|
219
|
+
/**
|
|
220
|
+
* Combines and validates visibility directives (only and skip) from both CLI and config sources.
|
|
221
|
+
* Ensures that no directive appears in both "only" and "skip" lists simultaneously.
|
|
222
|
+
*
|
|
223
|
+
* @param cliOpts - CLI options containing "only" and "skip" directives
|
|
224
|
+
* @param configFileOpts - Config file options containing directive configurations
|
|
225
|
+
* @returns An object with validated "onlyDocDirective" and "skipDocDirective" arrays
|
|
226
|
+
* @throws Error if the same directive appears in both "only" and "skip" lists
|
|
227
|
+
* @example
|
|
228
|
+
* ```typescript
|
|
229
|
+
* const cliOptions = { only: ["@example"], skip: ["@internal"] };
|
|
230
|
+
* const configOptions = { onlyDocDirective: ["@auth"] };
|
|
231
|
+
*
|
|
232
|
+
* const visibilityDirectives = getVisibilityDirectives(cliOptions, configOptions);
|
|
233
|
+
* console.log(visibilityDirectives);
|
|
234
|
+
* // {
|
|
235
|
+
* // onlyDocDirective: ["example", "auth"],
|
|
236
|
+
* // skipDocDirective: ["internal"]
|
|
237
|
+
* // }
|
|
238
|
+
*
|
|
239
|
+
* // Invalid - will throw an error
|
|
240
|
+
* getVisibilityDirectives(
|
|
241
|
+
* { only: ["@example"], skip: ["@example"] },
|
|
242
|
+
* {}
|
|
243
|
+
* ); // Error: The same directive cannot be declared in 'onlyDocDirective' and 'skipDocDirective'.
|
|
244
|
+
* ```
|
|
245
|
+
* @see {@link getOnlyDocDirectives} and {@link getSkipDocDirectives} for directive retrieval
|
|
246
|
+
*/
|
|
99
247
|
const getVisibilityDirectives = (cliOpts, configFileOpts) => {
|
|
100
248
|
const skipDocDirective = (0, exports.getSkipDocDirectives)(cliOpts, configFileOpts);
|
|
101
249
|
const onlyDocDirective = (0, exports.getOnlyDocDirectives)(cliOpts, configFileOpts);
|
|
@@ -107,6 +255,36 @@ const getVisibilityDirectives = (cliOpts, configFileOpts) => {
|
|
|
107
255
|
return { onlyDocDirective, skipDocDirective };
|
|
108
256
|
};
|
|
109
257
|
exports.getVisibilityDirectives = getVisibilityDirectives;
|
|
258
|
+
/**
|
|
259
|
+
* Processes custom directives, filtering out any that should be skipped.
|
|
260
|
+
* Validates that each custom directive has the correct format with required functions.
|
|
261
|
+
*
|
|
262
|
+
* @param customDirectiveOptions - The custom directive configuration object
|
|
263
|
+
* @param skipDocDirective - Array of directive names that should be skipped
|
|
264
|
+
* @returns The filtered custom directives object, or undefined if empty/invalid
|
|
265
|
+
* @throws Error if a custom directive has an invalid format
|
|
266
|
+
* @example
|
|
267
|
+
* ```typescript
|
|
268
|
+
* // Valid custom directive with tag function
|
|
269
|
+
* const customDirectives = {
|
|
270
|
+
* example: {
|
|
271
|
+
* tag: (value) => `Example: ${value}`
|
|
272
|
+
* },
|
|
273
|
+
* todo: {
|
|
274
|
+
* descriptor: () => "TODO items"
|
|
275
|
+
* }
|
|
276
|
+
* };
|
|
277
|
+
*
|
|
278
|
+
* // Filter out the "example" directive
|
|
279
|
+
* const filteredDirectives = getCustomDirectives(customDirectives, ["example"]);
|
|
280
|
+
* console.log(filteredDirectives); // { todo: { descriptor: [Function] } }
|
|
281
|
+
*
|
|
282
|
+
* // Invalid format - will throw an error
|
|
283
|
+
* getCustomDirectives({ example: { invalid: true } }, []);
|
|
284
|
+
* // Error: Wrong format for plugin custom directive "example"...
|
|
285
|
+
* ```
|
|
286
|
+
* @see {@link DOCS_URL}/advanced/custom-directive for custom directive format documentation
|
|
287
|
+
*/
|
|
110
288
|
const getCustomDirectives = (customDirectiveOptions, skipDocDirective) => {
|
|
111
289
|
if (!customDirectiveOptions ||
|
|
112
290
|
Object.keys(customDirectiveOptions).length === 0) {
|
|
@@ -128,16 +306,63 @@ const getCustomDirectives = (customDirectiveOptions, skipDocDirective) => {
|
|
|
128
306
|
: customDirectiveOptions;
|
|
129
307
|
};
|
|
130
308
|
exports.getCustomDirectives = getCustomDirectives;
|
|
309
|
+
/**
|
|
310
|
+
* Determines the diff method to use based on the configuration and force flag.
|
|
311
|
+
* If force is true, always returns FORCE regardless of the configured diff method.
|
|
312
|
+
*
|
|
313
|
+
* @param diff - The configured diff method
|
|
314
|
+
* @param force - Whether to force regeneration (overrides diff setting)
|
|
315
|
+
* @returns The resolved diff method to use
|
|
316
|
+
* @example
|
|
317
|
+
* ```typescript
|
|
318
|
+
* // Normal usage - respects the configured diff method
|
|
319
|
+
* const method1 = getDiffMethod(DiffMethod.NONE, false);
|
|
320
|
+
* console.log(method1); // "NONE"
|
|
321
|
+
*
|
|
322
|
+
* // Force flag overrides the diff method
|
|
323
|
+
* const method2 = getDiffMethod(DiffMethod.NONE, true);
|
|
324
|
+
* console.log(method2); // "FORCE"
|
|
325
|
+
* ```
|
|
326
|
+
* @see {@link DiffMethod} for available diff methods
|
|
327
|
+
*/
|
|
131
328
|
const getDiffMethod = (diff, force = false) => {
|
|
132
329
|
return force
|
|
133
330
|
? DiffMethod.FORCE
|
|
134
331
|
: diff.toLocaleUpperCase();
|
|
135
332
|
};
|
|
136
333
|
exports.getDiffMethod = getDiffMethod;
|
|
334
|
+
/**
|
|
335
|
+
* Placeholder function for handling deprecated document options.
|
|
336
|
+
* Currently returns an empty object as these options are deprecated.
|
|
337
|
+
*
|
|
338
|
+
* @param _cliOpts - Deprecated CLI options (unused)
|
|
339
|
+
* @param _configOptions - Deprecated config options (unused)
|
|
340
|
+
* @returns An empty object
|
|
341
|
+
*/
|
|
137
342
|
const parseDeprecatedDocOptions = (_cliOpts, _configOptions) => {
|
|
138
343
|
return {};
|
|
139
344
|
};
|
|
140
345
|
exports.parseDeprecatedDocOptions = parseDeprecatedDocOptions;
|
|
346
|
+
/**
|
|
347
|
+
* Builds the document options by merging CLI options, config file options, and defaults.
|
|
348
|
+
* Handles index generation flag and front matter configuration.
|
|
349
|
+
*
|
|
350
|
+
* @param cliOpts - CLI options for document generation
|
|
351
|
+
* @param configOptions - Config file options for document generation
|
|
352
|
+
* @returns The resolved document options with all required fields
|
|
353
|
+
* @example
|
|
354
|
+
* ```typescript
|
|
355
|
+
* const cliOptions = { index: true };
|
|
356
|
+
* const configOptions = { frontMatter: { sidebar_label: 'API' } };
|
|
357
|
+
*
|
|
358
|
+
* const docOptions = getDocOptions(cliOptions, configOptions);
|
|
359
|
+
* console.log(docOptions);
|
|
360
|
+
* // {
|
|
361
|
+
* // index: true,
|
|
362
|
+
* // frontMatter: { sidebar_label: 'API' }
|
|
363
|
+
* // }
|
|
364
|
+
* ```
|
|
365
|
+
*/
|
|
141
366
|
const getDocOptions = (cliOpts, configOptions) => {
|
|
142
367
|
const deprecated = (0, exports.parseDeprecatedDocOptions)(cliOpts, configOptions);
|
|
143
368
|
const index = typeof cliOpts?.index === "boolean"
|
|
@@ -154,6 +379,30 @@ const getDocOptions = (cliOpts, configOptions) => {
|
|
|
154
379
|
};
|
|
155
380
|
};
|
|
156
381
|
exports.getDocOptions = getDocOptions;
|
|
382
|
+
/**
|
|
383
|
+
* Resolves the type hierarchy configuration by merging CLI and config file options.
|
|
384
|
+
* Validates that CLI and config don't specify conflicting hierarchy types.
|
|
385
|
+
*
|
|
386
|
+
* @param cliOption - The hierarchy option specified via CLI (string value)
|
|
387
|
+
* @param configOption - The hierarchy option from the config file (string or object)
|
|
388
|
+
* @returns The resolved type hierarchy object
|
|
389
|
+
* @throws Error if CLI and config specify conflicting hierarchy types
|
|
390
|
+
* @example
|
|
391
|
+
* ```typescript
|
|
392
|
+
* // Using hierarchy from CLI (string format)
|
|
393
|
+
* const hierarchy1 = getTypeHierarchyOption("api", undefined);
|
|
394
|
+
* console.log(hierarchy1); // { api: {} }
|
|
395
|
+
*
|
|
396
|
+
* // Using hierarchy from config (object format)
|
|
397
|
+
* const hierarchy2 = getTypeHierarchyOption(undefined, { entity: { User: ["posts"] } });
|
|
398
|
+
* console.log(hierarchy2); // { entity: { User: ["posts"] } }
|
|
399
|
+
*
|
|
400
|
+
* // Error case - conflicting hierarchies
|
|
401
|
+
* getTypeHierarchyOption("api", { entity: {} });
|
|
402
|
+
* // Error: Hierarchy option mismatch in CLI flag 'api' and config 'entity'
|
|
403
|
+
* ```
|
|
404
|
+
* @see {@link TypeHierarchy} for available hierarchy types
|
|
405
|
+
*/
|
|
157
406
|
const getTypeHierarchyOption = (cliOption, configOption) => {
|
|
158
407
|
const parseValue = (config) => {
|
|
159
408
|
if (typeof config === "string") {
|
|
@@ -185,10 +434,48 @@ const getTypeHierarchyOption = (cliOption, configOption) => {
|
|
|
185
434
|
return cliHierarchy ?? configHierarchy ?? exports.DEFAULT_HIERARCHY;
|
|
186
435
|
};
|
|
187
436
|
exports.getTypeHierarchyOption = getTypeHierarchyOption;
|
|
437
|
+
/**
|
|
438
|
+
* Placeholder function for handling deprecated print type options.
|
|
439
|
+
* Currently returns an empty object as these options are deprecated.
|
|
440
|
+
*
|
|
441
|
+
* @param _cliOpts - Deprecated CLI options (unused)
|
|
442
|
+
* @param _configOptions - Deprecated config options (unused)
|
|
443
|
+
* @returns An empty object
|
|
444
|
+
*/
|
|
188
445
|
const parseDeprecatedPrintTypeOptions = (_cliOpts, _configOptions) => {
|
|
189
446
|
return {};
|
|
190
447
|
};
|
|
191
448
|
exports.parseDeprecatedPrintTypeOptions = parseDeprecatedPrintTypeOptions;
|
|
449
|
+
/**
|
|
450
|
+
* Builds the print type options by merging CLI options, config file options, and defaults.
|
|
451
|
+
* Handles various formatting options for type documentation.
|
|
452
|
+
*
|
|
453
|
+
* @param cliOpts - CLI options for print type configuration
|
|
454
|
+
* @param configOptions - Config file options for print type configuration
|
|
455
|
+
* @returns The resolved print type options with all required fields
|
|
456
|
+
* @example
|
|
457
|
+
* ```typescript
|
|
458
|
+
* const cliOptions = { noCode: true, deprecated: "group" };
|
|
459
|
+
* const configOptions = {
|
|
460
|
+
* exampleSection: true,
|
|
461
|
+
* hierarchy: "entity"
|
|
462
|
+
* };
|
|
463
|
+
*
|
|
464
|
+
* const printOptions = getPrintTypeOptions(cliOptions, configOptions);
|
|
465
|
+
* console.log(printOptions);
|
|
466
|
+
* // {
|
|
467
|
+
* // codeSection: false, // Disabled via noCode CLI flag
|
|
468
|
+
* // deprecated: "group", // From CLI
|
|
469
|
+
* // exampleSection: true, // From config
|
|
470
|
+
* // parentTypePrefix: true, // Default value
|
|
471
|
+
* // relatedTypeSection: true, // Default value
|
|
472
|
+
* // typeBadges: true, // Default value
|
|
473
|
+
* // hierarchy: { entity: {} } // Parsed from config
|
|
474
|
+
* // }
|
|
475
|
+
* ```
|
|
476
|
+
* @see {@link DeprecatedOption} for deprecated handling options
|
|
477
|
+
* @see {@link getTypeHierarchyOption} for hierarchy resolution
|
|
478
|
+
*/
|
|
192
479
|
const getPrintTypeOptions = (cliOpts, configOptions) => {
|
|
193
480
|
const deprecated = (0, exports.parseDeprecatedPrintTypeOptions)(cliOpts, configOptions);
|
|
194
481
|
return {
|
|
@@ -210,6 +497,33 @@ const getPrintTypeOptions = (cliOpts, configOptions) => {
|
|
|
210
497
|
};
|
|
211
498
|
};
|
|
212
499
|
exports.getPrintTypeOptions = getPrintTypeOptions;
|
|
500
|
+
/**
|
|
501
|
+
* Parses and validates the groupByDirective option string format.
|
|
502
|
+
* The format should be \@directive(field|=fallback) where:
|
|
503
|
+
* - directive: Name of the directive to group by
|
|
504
|
+
* - field: Name of the field in the directive to use for grouping
|
|
505
|
+
* - fallback: (Optional) Fallback group name for items without the directive
|
|
506
|
+
*
|
|
507
|
+
* @param groupOptions - The group directive option as a string
|
|
508
|
+
* @returns A parsed GroupByDirectiveOptions object or undefined if invalid
|
|
509
|
+
* @throws Error if the groupByDirective format is invalid
|
|
510
|
+
* @example
|
|
511
|
+
* ```typescript
|
|
512
|
+
* // Basic usage with directive and field
|
|
513
|
+
* const groupBy1 = parseGroupByOption("@tag(name)");
|
|
514
|
+
* console.log(groupBy1);
|
|
515
|
+
* // { directive: "tag", field: "name", fallback: "Miscellaneous" }
|
|
516
|
+
*
|
|
517
|
+
* // With custom fallback group
|
|
518
|
+
* const groupBy2 = parseGroupByOption("@category(name|=Other)");
|
|
519
|
+
* console.log(groupBy2);
|
|
520
|
+
* // { directive: "category", field: "name", fallback: "Other" }
|
|
521
|
+
*
|
|
522
|
+
* // Invalid format - will throw an error
|
|
523
|
+
* parseGroupByOption("invalid-format");
|
|
524
|
+
* // Error: Invalid "invalid-format"
|
|
525
|
+
* ```
|
|
526
|
+
*/
|
|
213
527
|
const parseGroupByOption = (groupOptions) => {
|
|
214
528
|
const DEFAULT_GROUP = "Miscellaneous";
|
|
215
529
|
const OPTION_REGEX = /^@(?<directive>\w+)\((?<field>\w+)(?:\|=(?<fallback>\w+))?\)/;
|
|
@@ -227,10 +541,55 @@ const parseGroupByOption = (groupOptions) => {
|
|
|
227
541
|
return { directive, field, fallback };
|
|
228
542
|
};
|
|
229
543
|
exports.parseGroupByOption = parseGroupByOption;
|
|
230
|
-
const
|
|
231
|
-
if (
|
|
232
|
-
|
|
544
|
+
const parseHomepageOption = (cliHomepage, configHomepage) => {
|
|
545
|
+
if (typeof cliHomepage === "string") {
|
|
546
|
+
return cliHomepage;
|
|
547
|
+
}
|
|
548
|
+
if (configHomepage === false) {
|
|
549
|
+
return undefined;
|
|
550
|
+
}
|
|
551
|
+
if (typeof configHomepage === "string") {
|
|
552
|
+
return configHomepage;
|
|
233
553
|
}
|
|
554
|
+
return exports.DEFAULT_OPTIONS.homepage;
|
|
555
|
+
};
|
|
556
|
+
exports.parseHomepageOption = parseHomepageOption;
|
|
557
|
+
/**
|
|
558
|
+
* Builds the complete configuration object by merging options from multiple sources
|
|
559
|
+
* in order of precedence:
|
|
560
|
+
* 1. CLI options (highest priority)
|
|
561
|
+
* 2. Configuration file options
|
|
562
|
+
* 3. GraphQL Config options
|
|
563
|
+
* 4. Default options (lowest priority)
|
|
564
|
+
*
|
|
565
|
+
* @param configFileOpts - Options from the configuration file
|
|
566
|
+
* @param cliOpts - Options from the command line interface
|
|
567
|
+
* @param id - The configuration ID used when referencing multiple schemas
|
|
568
|
+
* @returns A promise resolving to the final merged configuration object
|
|
569
|
+
* @example
|
|
570
|
+
* ```typescript
|
|
571
|
+
* // Basic usage with minimal options
|
|
572
|
+
* const config = await buildConfig(
|
|
573
|
+
* { baseURL: "api" }, // Config file options
|
|
574
|
+
* { pretty: true } // CLI options
|
|
575
|
+
* );
|
|
576
|
+
*
|
|
577
|
+
* // With specific config ID
|
|
578
|
+
* const config = await buildConfig(
|
|
579
|
+
* { schema: "./schemas/users.graphql" },
|
|
580
|
+
* { force: true },
|
|
581
|
+
* "users"
|
|
582
|
+
* );
|
|
583
|
+
*
|
|
584
|
+
* // The resulting config will contain all required options
|
|
585
|
+
* // with values from CLI taking precedence over config file,
|
|
586
|
+
* // and defaults filling in any missing values
|
|
587
|
+
* ```
|
|
588
|
+
* @see {@link Options} for the complete configuration interface
|
|
589
|
+
* @see {@link DEFAULT_OPTIONS} for default values
|
|
590
|
+
*/
|
|
591
|
+
const buildConfig = async (configFileOpts, cliOpts, id = "default") => {
|
|
592
|
+
cliOpts ??= {};
|
|
234
593
|
const graphqlConfig = await (0, graphql_config_1.loadConfiguration)(id);
|
|
235
594
|
const config = {
|
|
236
595
|
...exports.DEFAULT_OPTIONS,
|
|
@@ -247,7 +606,7 @@ const buildConfig = async (configFileOpts, cliOpts, id = "default") => {
|
|
|
247
606
|
docOptions: (0, exports.getDocOptions)(cliOpts, config.docOptions),
|
|
248
607
|
force,
|
|
249
608
|
groupByDirective: (0, exports.parseGroupByOption)(cliOpts.groupByDirective) ?? config.groupByDirective,
|
|
250
|
-
homepageLocation: cliOpts.homepage
|
|
609
|
+
homepageLocation: (0, exports.parseHomepageOption)(cliOpts.homepage, config.homepage),
|
|
251
610
|
id: id ?? exports.DEFAULT_OPTIONS.id,
|
|
252
611
|
linkRoot: cliOpts.link ?? config.linkRoot ?? exports.DEFAULT_OPTIONS.linkRoot,
|
|
253
612
|
loaders: config.loaders,
|
package/dist/diff.d.ts
CHANGED
|
@@ -1,2 +1,53 @@
|
|
|
1
1
|
import type { DiffMethodName, GraphQLSchema, Maybe } from "@graphql-markdown/types";
|
|
2
|
+
/**
|
|
3
|
+
* Module for detecting changes in GraphQL schemas.
|
|
4
|
+
* This module provides functionality to compare GraphQL schemas and detect changes.
|
|
5
|
+
*
|
|
6
|
+
* @module diff
|
|
7
|
+
* @category Core
|
|
8
|
+
* @since 1.0.0
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Determines if there are changes in the GraphQL schema by using a specified diff method and module.
|
|
12
|
+
*
|
|
13
|
+
* @param schema - The GraphQL schema to check for changes.
|
|
14
|
+
* @param tmpDir - The temporary directory to store intermediate files during the diff process.
|
|
15
|
+
* @param diffMethod - The name of the diff method to use. Must be a string or `null`.
|
|
16
|
+
* @param diffModule - The module to import for performing the diff. Defaults to `@graphql-markdown/diff`.
|
|
17
|
+
* @returns A promise that resolves to `true` if changes are detected or if the diff method/module is invalid, otherwise `false`.
|
|
18
|
+
*
|
|
19
|
+
* @example
|
|
20
|
+
* ```typescript
|
|
21
|
+
* import { hasChanges } from "./diff";
|
|
22
|
+
* import { buildSchema } from "graphql";
|
|
23
|
+
*
|
|
24
|
+
* const schema = buildSchema(`
|
|
25
|
+
* type Query {
|
|
26
|
+
* hello: String
|
|
27
|
+
* }
|
|
28
|
+
* `);
|
|
29
|
+
*
|
|
30
|
+
* const changesDetected = await hasChanges(schema, "/tmp", "methodName");
|
|
31
|
+
* console.log(changesDetected); // true or false
|
|
32
|
+
* ```
|
|
33
|
+
*
|
|
34
|
+
* @example Using with a custom diff module
|
|
35
|
+
* ```typescript
|
|
36
|
+
* import { hasChanges } from "./diff";
|
|
37
|
+
*
|
|
38
|
+
* const schema = getMySchema();
|
|
39
|
+
* const result = await hasChanges(
|
|
40
|
+
* schema,
|
|
41
|
+
* "/tmp/schema-diff",
|
|
42
|
+
* "breaking",
|
|
43
|
+
* "./my-custom-diff-module"
|
|
44
|
+
* );
|
|
45
|
+
* ```
|
|
46
|
+
*
|
|
47
|
+
* @throws Will log a warning if the specified diff module cannot be found.
|
|
48
|
+
* @see {@link DiffMethodName} for available diff methods
|
|
49
|
+
* @see {@link FunctionCheckSchemaChanges} for the signature of the function imported from the diff module
|
|
50
|
+
* @category Schema
|
|
51
|
+
* @since 1.0.0
|
|
52
|
+
*/
|
|
2
53
|
export declare const hasChanges: (schema: GraphQLSchema, tmpDir: string, diffMethod: Maybe<DiffMethodName>, diffModule?: Maybe<string>) => Promise<boolean>;
|
package/dist/diff.js
CHANGED
|
@@ -35,6 +35,57 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.hasChanges = void 0;
|
|
37
37
|
const logger_1 = require("@graphql-markdown/logger");
|
|
38
|
+
/**
|
|
39
|
+
* Module for detecting changes in GraphQL schemas.
|
|
40
|
+
* This module provides functionality to compare GraphQL schemas and detect changes.
|
|
41
|
+
*
|
|
42
|
+
* @module diff
|
|
43
|
+
* @category Core
|
|
44
|
+
* @since 1.0.0
|
|
45
|
+
*/
|
|
46
|
+
/**
|
|
47
|
+
* Determines if there are changes in the GraphQL schema by using a specified diff method and module.
|
|
48
|
+
*
|
|
49
|
+
* @param schema - The GraphQL schema to check for changes.
|
|
50
|
+
* @param tmpDir - The temporary directory to store intermediate files during the diff process.
|
|
51
|
+
* @param diffMethod - The name of the diff method to use. Must be a string or `null`.
|
|
52
|
+
* @param diffModule - The module to import for performing the diff. Defaults to `@graphql-markdown/diff`.
|
|
53
|
+
* @returns A promise that resolves to `true` if changes are detected or if the diff method/module is invalid, otherwise `false`.
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* ```typescript
|
|
57
|
+
* import { hasChanges } from "./diff";
|
|
58
|
+
* import { buildSchema } from "graphql";
|
|
59
|
+
*
|
|
60
|
+
* const schema = buildSchema(`
|
|
61
|
+
* type Query {
|
|
62
|
+
* hello: String
|
|
63
|
+
* }
|
|
64
|
+
* `);
|
|
65
|
+
*
|
|
66
|
+
* const changesDetected = await hasChanges(schema, "/tmp", "methodName");
|
|
67
|
+
* console.log(changesDetected); // true or false
|
|
68
|
+
* ```
|
|
69
|
+
*
|
|
70
|
+
* @example Using with a custom diff module
|
|
71
|
+
* ```typescript
|
|
72
|
+
* import { hasChanges } from "./diff";
|
|
73
|
+
*
|
|
74
|
+
* const schema = getMySchema();
|
|
75
|
+
* const result = await hasChanges(
|
|
76
|
+
* schema,
|
|
77
|
+
* "/tmp/schema-diff",
|
|
78
|
+
* "breaking",
|
|
79
|
+
* "./my-custom-diff-module"
|
|
80
|
+
* );
|
|
81
|
+
* ```
|
|
82
|
+
*
|
|
83
|
+
* @throws Will log a warning if the specified diff module cannot be found.
|
|
84
|
+
* @see {@link DiffMethodName} for available diff methods
|
|
85
|
+
* @see {@link FunctionCheckSchemaChanges} for the signature of the function imported from the diff module
|
|
86
|
+
* @category Schema
|
|
87
|
+
* @since 1.0.0
|
|
88
|
+
*/
|
|
38
89
|
const hasChanges = async (schema, tmpDir, diffMethod, diffModule = "@graphql-markdown/diff") => {
|
|
39
90
|
if (typeof diffMethod !== "string" || typeof diffModule !== "string") {
|
|
40
91
|
return true;
|
package/dist/generator.d.ts
CHANGED
|
@@ -1,2 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Core generator functionality for GraphQL Markdown documentation.
|
|
3
|
+
*
|
|
4
|
+
* This module contains the main functionality for generating markdown documentation
|
|
5
|
+
* from GraphQL schemas. It handles schema loading, processing, and markdown generation
|
|
6
|
+
* through appropriate printers and renderers.
|
|
7
|
+
*
|
|
8
|
+
* @packageDocumentation
|
|
9
|
+
*/
|
|
1
10
|
import type { GeneratorOptions } from "@graphql-markdown/types";
|
|
11
|
+
/**
|
|
12
|
+
* Main entry point for generating Markdown documentation from a GraphQL schema.
|
|
13
|
+
*
|
|
14
|
+
* This function coordinates the entire documentation generation process:
|
|
15
|
+
* - Loads and validates the schema
|
|
16
|
+
* - Checks for schema changes if diffing is enabled
|
|
17
|
+
* - Processes directives and groups
|
|
18
|
+
* - Initializes printers and renderers
|
|
19
|
+
* - Generates markdown files
|
|
20
|
+
*
|
|
21
|
+
* @param options - Complete configuration for the documentation generation
|
|
22
|
+
* @returns Promise that resolves when documentation is fully generated
|
|
23
|
+
*/
|
|
2
24
|
export declare const generateDocFromSchema: ({ baseURL, customDirective, diffMethod, docOptions, force, groupByDirective, homepageLocation, linkRoot, loaders: loadersList, loggerModule, mdxParser, metatags, onlyDocDirective, outputDir, prettify, printer: printerModule, printTypeOptions, schemaLocation, skipDocDirective, tmpDir, }: GeneratorOptions) => Promise<void>;
|
package/dist/generator.js
CHANGED
|
@@ -41,8 +41,32 @@ const config_1 = require("./config");
|
|
|
41
41
|
const diff_1 = require("./diff");
|
|
42
42
|
const printer_1 = require("./printer");
|
|
43
43
|
const renderer_1 = require("./renderer");
|
|
44
|
+
/**
|
|
45
|
+
* Constant representing nanoseconds per second.
|
|
46
|
+
*
|
|
47
|
+
* This constant is used for high-precision time measurements and conversions
|
|
48
|
+
* between seconds and nanoseconds.
|
|
49
|
+
*
|
|
50
|
+
*/
|
|
44
51
|
const NS_PER_SEC = 1e9;
|
|
52
|
+
/**
|
|
53
|
+
* The number of decimal places to display when reporting times in seconds.
|
|
54
|
+
*
|
|
55
|
+
*/
|
|
45
56
|
const SEC_DECIMALS = 3;
|
|
57
|
+
/**
|
|
58
|
+
* Main entry point for generating Markdown documentation from a GraphQL schema.
|
|
59
|
+
*
|
|
60
|
+
* This function coordinates the entire documentation generation process:
|
|
61
|
+
* - Loads and validates the schema
|
|
62
|
+
* - Checks for schema changes if diffing is enabled
|
|
63
|
+
* - Processes directives and groups
|
|
64
|
+
* - Initializes printers and renderers
|
|
65
|
+
* - Generates markdown files
|
|
66
|
+
*
|
|
67
|
+
* @param options - Complete configuration for the documentation generation
|
|
68
|
+
* @returns Promise that resolves when documentation is fully generated
|
|
69
|
+
*/
|
|
46
70
|
const generateDocFromSchema = async ({ baseURL, customDirective, diffMethod, docOptions, force, groupByDirective, homepageLocation, linkRoot, loaders: loadersList, loggerModule, mdxParser, metatags, onlyDocDirective, outputDir, prettify, printer: printerModule, printTypeOptions, schemaLocation, skipDocDirective, tmpDir, }) => {
|
|
47
71
|
const start = process.hrtime.bigint();
|
|
48
72
|
await (0, logger_1.default)(loggerModule);
|