@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/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
20
  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;
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,42 @@ const parseGroupByOption = (groupOptions) => {
227
541
  return { directive, field, fallback };
228
542
  };
229
543
  exports.parseGroupByOption = parseGroupByOption;
544
+ /**
545
+ * Builds the complete configuration object by merging options from multiple sources
546
+ * in order of precedence:
547
+ * 1. CLI options (highest priority)
548
+ * 2. Configuration file options
549
+ * 3. GraphQL Config options
550
+ * 4. Default options (lowest priority)
551
+ *
552
+ * @param configFileOpts - Options from the configuration file
553
+ * @param cliOpts - Options from the command line interface
554
+ * @param id - The configuration ID used when referencing multiple schemas
555
+ * @returns A promise resolving to the final merged configuration object
556
+ * @example
557
+ * ```typescript
558
+ * // Basic usage with minimal options
559
+ * const config = await buildConfig(
560
+ * { baseURL: "api" }, // Config file options
561
+ * { pretty: true } // CLI options
562
+ * );
563
+ *
564
+ * // With specific config ID
565
+ * const config = await buildConfig(
566
+ * { schema: "./schemas/users.graphql" },
567
+ * { force: true },
568
+ * "users"
569
+ * );
570
+ *
571
+ * // The resulting config will contain all required options
572
+ * // with values from CLI taking precedence over config file,
573
+ * // and defaults filling in any missing values
574
+ * ```
575
+ * @see {@link Options} for the complete configuration interface
576
+ * @see {@link DEFAULT_OPTIONS} for default values
577
+ */
230
578
  const buildConfig = async (configFileOpts, cliOpts, id = "default") => {
231
- if (!cliOpts) {
232
- cliOpts = {};
233
- }
579
+ cliOpts ??= {};
234
580
  const graphqlConfig = await (0, graphql_config_1.loadConfiguration)(id);
235
581
  const config = {
236
582
  ...exports.DEFAULT_OPTIONS,
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;
@@ -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,11 +41,34 @@ 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
- const hasMDXSupport = mdxParser ? true : false;
49
72
  await (0, logger_1.default)(loggerModule);
50
73
  const loaders = await (0, graphql_1.getDocumentLoaders)(loadersList);
51
74
  if (!loaders) {
@@ -74,6 +97,12 @@ const generateDocFromSchema = async ({ baseURL, customDirective, diffMethod, doc
74
97
  const rootTypes = (0, graphql_1.getSchemaMap)(schema);
75
98
  const customDirectives = (0, graphql_1.getCustomDirectives)(rootTypes, customDirective);
76
99
  const groups = (0, graphql_1.getGroups)(rootTypes, groupByDirective);
100
+ const mdxModule = await (!mdxParser
101
+ ? undefined
102
+ : Promise.resolve(`${mdxParser}`).then(s => __importStar(require(s))).catch(() => {
103
+ (0, logger_1.log)(`An error occurred while loading MDX formatter "${mdxParser}"`, logger_1.LogLevel.warn);
104
+ return undefined;
105
+ }));
77
106
  const printer = await (0, printer_1.getPrinter)(
78
107
  // module mandatory
79
108
  printerModule,
@@ -95,13 +124,13 @@ const generateDocFromSchema = async ({ baseURL, customDirective, diffMethod, doc
95
124
  onlyDocDirectives,
96
125
  printTypeOptions,
97
126
  skipDocDirectives,
98
- }, mdxParser);
127
+ }, mdxModule);
99
128
  const renderer = await (0, renderer_1.getRenderer)(printer, outputDir, baseURL, groups, prettify, {
100
129
  ...docOptions,
101
130
  deprecated: printTypeOptions?.deprecated,
102
131
  force,
103
132
  hierarchy: printTypeOptions?.hierarchy,
104
- }, hasMDXSupport);
133
+ }, mdxModule);
105
134
  const pages = await Promise.all(Object.keys(rootTypes).map(async (name) => {
106
135
  const typeName = name;
107
136
  return renderer.renderRootTypes(typeName, rootTypes[typeName]);