@graphql-markdown/core 1.17.0 → 1.17.2

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.
Files changed (58) hide show
  1. package/dist/event-handlers.d.ts +6 -3
  2. package/dist/event-handlers.d.ts.map +1 -1
  3. package/dist/event-handlers.js +10 -7
  4. package/dist/event-map.d.ts +3 -0
  5. package/dist/event-map.d.ts.map +1 -1
  6. package/dist/event-map.js +3 -0
  7. package/dist/events/base.d.ts +8 -3
  8. package/dist/events/base.d.ts.map +1 -1
  9. package/dist/events/base.js +6 -5
  10. package/dist/events/diff-check.d.ts +11 -11
  11. package/dist/events/diff-check.d.ts.map +1 -1
  12. package/dist/events/diff-check.js +5 -8
  13. package/dist/events/generate-index-metafile.d.ts +8 -11
  14. package/dist/events/generate-index-metafile.d.ts.map +1 -1
  15. package/dist/events/generate-index-metafile.js +5 -11
  16. package/dist/events/index.d.ts +1 -1
  17. package/dist/events/index.d.ts.map +1 -1
  18. package/dist/events/index.js +2 -2
  19. package/dist/events/print-type-events.d.ts +33 -0
  20. package/dist/events/print-type-events.d.ts.map +1 -0
  21. package/dist/events/print-type-events.js +35 -0
  22. package/dist/events/print-type.d.ts +84 -0
  23. package/dist/events/print-type.d.ts.map +1 -0
  24. package/dist/events/print-type.js +73 -0
  25. package/dist/events/render-homepage.d.ts +6 -7
  26. package/dist/events/render-homepage.d.ts.map +1 -1
  27. package/dist/events/render-homepage.js +5 -5
  28. package/dist/events/render-root-types.d.ts +6 -7
  29. package/dist/events/render-root-types.d.ts.map +1 -1
  30. package/dist/events/render-root-types.js +5 -5
  31. package/dist/events/render-type-entities.d.ts +7 -9
  32. package/dist/events/render-type-entities.d.ts.map +1 -1
  33. package/dist/events/render-type-entities.js +5 -8
  34. package/dist/events/schema-events.d.ts +4 -0
  35. package/dist/events/schema-events.d.ts.map +1 -1
  36. package/dist/events/schema-events.js +4 -0
  37. package/dist/events/schema-load.d.ts +13 -9
  38. package/dist/events/schema-load.d.ts.map +1 -1
  39. package/dist/events/schema-load.js +8 -8
  40. package/dist/generator.d.ts +79 -1
  41. package/dist/generator.d.ts.map +1 -1
  42. package/dist/generator.js +217 -49
  43. package/dist/index.d.ts +7 -1
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +14 -1
  46. package/dist/printer.d.ts +3 -3
  47. package/dist/printer.d.ts.map +1 -1
  48. package/dist/printer.js +3 -3
  49. package/dist/renderer.d.ts +10 -10
  50. package/dist/renderer.d.ts.map +1 -1
  51. package/dist/renderer.js +11 -21
  52. package/package.json +9 -9
  53. package/dist/event-types.d.ts +0 -313
  54. package/dist/event-types.d.ts.map +0 -1
  55. package/dist/event-types.js +0 -309
  56. package/dist/hooks.d.ts +0 -10
  57. package/dist/hooks.d.ts.map +0 -1
  58. package/dist/hooks.js +0 -33
@@ -1 +1 @@
1
- {"version":3,"file":"render-root-types.d.ts","sourceRoot":"","sources":["../../src/events/render-root-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAE1C;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;IACxD,2BAA2B;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,YAAY,IAAI,EAAE;QAChB,SAAS,EAAE,OAAO,CAAC;QACnB,aAAa,CAAC,EAAE,aAAa,CAAC;QAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,EAGA;CACF"}
1
+ {"version":3,"file":"render-root-types.d.ts","sourceRoot":"","sources":["../../src/events/render-root-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AAEnE;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;IACxD,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE;QACb,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;IAEF,YACE,IAAI,EAAE;QACJ,SAAS,EAAE,OAAO,CAAC;KACpB,EACD,OAAO,CAAC,EAAE,uBAAuB,EAIlC;CACF"}
@@ -13,11 +13,11 @@ const base_1 = require("./base");
13
13
  * @category Events
14
14
  */
15
15
  class RenderRootTypesEvent extends base_1.CancellableEvent {
16
- /** Root types to render */
17
- rootTypes;
18
- constructor(data) {
19
- super(data.cancellable, data.defaultAction);
20
- this.rootTypes = data.rootTypes;
16
+ /** Event data containing root types */
17
+ data;
18
+ constructor(data, options) {
19
+ super(options);
20
+ this.data = data;
21
21
  }
22
22
  }
23
23
  exports.RenderRootTypesEvent = RenderRootTypesEvent;
@@ -3,23 +3,21 @@
3
3
  *
4
4
  * @packageDocumentation
5
5
  */
6
- import type { DefaultAction } from "@graphql-markdown/types";
7
- import { CancellableEvent } from "./base";
6
+ import { CancellableEvent, CancellableEventOptions } from "./base";
8
7
  /**
9
8
  * Event emitted before/after rendering type entities.
10
9
  *
11
10
  * @category Events
12
11
  */
13
12
  export declare class RenderTypeEntitiesEvent extends CancellableEvent {
14
- /** Name of the type entity */
15
- readonly name: string;
16
- /** File path where entity will be rendered */
17
- readonly filePath: string;
13
+ /** Event data containing name and file path */
14
+ readonly data: {
15
+ name: string;
16
+ filePath: string;
17
+ };
18
18
  constructor(data: {
19
19
  name: string;
20
20
  filePath: string;
21
- defaultAction?: DefaultAction;
22
- cancellable?: boolean;
23
- });
21
+ }, options?: CancellableEventOptions);
24
22
  }
25
23
  //# sourceMappingURL=render-type-entities.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"render-type-entities.d.ts","sourceRoot":"","sources":["../../src/events/render-type-entities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAE1C;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,gBAAgB;IAC3D,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,YAAY,IAAI,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,aAAa,CAAC;QAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,EAIA;CACF"}
1
+ {"version":3,"file":"render-type-entities.d.ts","sourceRoot":"","sources":["../../src/events/render-type-entities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AAEnE;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,gBAAgB;IAC3D,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF,YACE,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,EACD,OAAO,CAAC,EAAE,uBAAuB,EAIlC;CACF"}
@@ -13,14 +13,11 @@ const base_1 = require("./base");
13
13
  * @category Events
14
14
  */
15
15
  class RenderTypeEntitiesEvent extends base_1.CancellableEvent {
16
- /** Name of the type entity */
17
- name;
18
- /** File path where entity will be rendered */
19
- filePath;
20
- constructor(data) {
21
- super(data.cancellable, data.defaultAction);
22
- this.name = data.name;
23
- this.filePath = data.filePath;
16
+ /** Event data containing name and file path */
17
+ data;
18
+ constructor(data, options) {
19
+ super(options);
20
+ this.data = data;
24
21
  }
25
22
  }
26
23
  exports.RenderTypeEntitiesEvent = RenderTypeEntitiesEvent;
@@ -11,5 +11,9 @@ export declare const SchemaEvents: {
11
11
  readonly BEFORE_LOAD: "schema:beforeLoad";
12
12
  /** Emitted after loading GraphQL schema */
13
13
  readonly AFTER_LOAD: "schema:afterLoad";
14
+ /** Emitted before mapping GraphQL schema */
15
+ readonly BEFORE_MAP: "schema:beforeMap";
16
+ /** Emitted after mapping GraphQL schema */
17
+ readonly AFTER_MAP: "schema:afterMap";
14
18
  };
15
19
  //# sourceMappingURL=schema-events.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"schema-events.d.ts","sourceRoot":"","sources":["../../src/events/schema-events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB,4CAA4C;;IAE5C,2CAA2C;;CAEnC,CAAC"}
1
+ {"version":3,"file":"schema-events.d.ts","sourceRoot":"","sources":["../../src/events/schema-events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB,4CAA4C;;IAE5C,2CAA2C;;IAE3C,4CAA4C;;IAE5C,2CAA2C;;CAEnC,CAAC"}
@@ -14,4 +14,8 @@ exports.SchemaEvents = {
14
14
  BEFORE_LOAD: "schema:beforeLoad",
15
15
  /** Emitted after loading GraphQL schema */
16
16
  AFTER_LOAD: "schema:afterLoad",
17
+ /** Emitted before mapping GraphQL schema */
18
+ BEFORE_MAP: "schema:beforeMap",
19
+ /** Emitted after mapping GraphQL schema */
20
+ AFTER_MAP: "schema:afterMap",
17
21
  };
@@ -3,20 +3,24 @@
3
3
  *
4
4
  * @packageDocumentation
5
5
  */
6
- import type { DefaultAction } from "@graphql-markdown/types";
7
- import { CancellableEvent } from "./base";
6
+ import type { GraphQLSchema, Maybe, SchemaMap } from "@graphql-markdown/types";
7
+ import { CancellableEvent, CancellableEventOptions } from "./base";
8
8
  /**
9
9
  * Event emitted before/after loading a GraphQL schema.
10
10
  *
11
11
  * @category Events
12
12
  */
13
- export declare class SchemaLoadEvent extends CancellableEvent {
14
- /** Path or pointer to the schema location */
15
- readonly schemaLocation: string;
13
+ export declare class SchemaEvent extends CancellableEvent {
14
+ /** Event data containing schema location, schema, and root types */
15
+ readonly data: {
16
+ schemaLocation?: string;
17
+ schema?: Maybe<GraphQLSchema>;
18
+ rootTypes?: Maybe<SchemaMap>;
19
+ };
16
20
  constructor(data: {
17
- schemaLocation: string;
18
- defaultAction?: DefaultAction;
19
- cancellable?: boolean;
20
- });
21
+ schemaLocation?: string;
22
+ schema?: Maybe<GraphQLSchema>;
23
+ rootTypes?: Maybe<SchemaMap>;
24
+ }, options?: CancellableEventOptions);
21
25
  }
22
26
  //# sourceMappingURL=schema-load.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"schema-load.d.ts","sourceRoot":"","sources":["../../src/events/schema-load.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAE1C;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,gBAAgB;IACnD,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,YAAY,IAAI,EAAE;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,CAAC,EAAE,aAAa,CAAC;QAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,EAGA;CACF"}
1
+ {"version":3,"file":"schema-load.d.ts","sourceRoot":"","sources":["../../src/events/schema-load.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AAEnE;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,gBAAgB;IAC/C,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE;QACb,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;QAC9B,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;KAC9B,CAAC;IAEF,YACE,IAAI,EAAE;QACJ,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;QAC9B,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;KAC9B,EACD,OAAO,CAAC,EAAE,uBAAuB,EAIlC;CACF"}
@@ -5,19 +5,19 @@
5
5
  * @packageDocumentation
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.SchemaLoadEvent = void 0;
8
+ exports.SchemaEvent = void 0;
9
9
  const base_1 = require("./base");
10
10
  /**
11
11
  * Event emitted before/after loading a GraphQL schema.
12
12
  *
13
13
  * @category Events
14
14
  */
15
- class SchemaLoadEvent extends base_1.CancellableEvent {
16
- /** Path or pointer to the schema location */
17
- schemaLocation;
18
- constructor(data) {
19
- super(data.cancellable, data.defaultAction);
20
- this.schemaLocation = data.schemaLocation;
15
+ class SchemaEvent extends base_1.CancellableEvent {
16
+ /** Event data containing schema location, schema, and root types */
17
+ data;
18
+ constructor(data, options) {
19
+ super(options);
20
+ this.data = data;
21
21
  }
22
22
  }
23
- exports.SchemaLoadEvent = SchemaLoadEvent;
23
+ exports.SchemaEvent = SchemaEvent;
@@ -7,7 +7,85 @@
7
7
  *
8
8
  * @packageDocumentation
9
9
  */
10
- import type { GeneratorOptions } from "@graphql-markdown/types";
10
+ import type { DirectiveName, Formatter, GeneratorOptions, GraphQLDirective, GraphQLSchema, LoaderOption, Maybe, MetaInfo, PackageName, TypeDiffMethod } from "@graphql-markdown/types";
11
+ /**
12
+ * Supported file extensions for generated documentation files.
13
+ *
14
+ * @remarks
15
+ * - MDX: MDX file extension (.mdx) for React component-enabled markdown
16
+ * - MD: Standard markdown file extension (.md)
17
+ */
18
+ export declare const FILE_EXTENSION: {
19
+ readonly MDX: ".mdx";
20
+ readonly MD: ".md";
21
+ };
22
+ /**
23
+ * Asynchronously loads an MDX module dynamically.
24
+ *
25
+ * @param mdxParser - The MDX parser package name or path to import. Can be null or undefined.
26
+ * @returns A promise that resolves to the imported module, or undefined if:
27
+ * - The mdxParser parameter is null or undefined
28
+ * - An error occurs during import (logs a warning and returns undefined)
29
+ *
30
+ * @internal
31
+ */
32
+ export declare const loadMDXModule: (mdxParser: Maybe<string | PackageName>) => Promise<unknown>;
33
+ /**
34
+ * Extracts a formatter from an MDX module.
35
+ *
36
+ * Checks for formatter functions in the following order:
37
+ * 1. A `createMDXFormatter` factory function (for internal/advanced usage)
38
+ * 2. Individual exported formatter functions (e.g., `formatMDXBadge`, `formatMDXAdmonition`)
39
+ *
40
+ * @param mdxModule - The loaded MDX module that may contain formatter exports
41
+ * @param meta - Optional metadata to pass to the formatter factory
42
+ * @returns A partial Formatter with the found functions, or undefined if none found
43
+ *
44
+ * @internal
45
+ */
46
+ export declare const getFormatterFromMDXModule: (mdxModule: unknown, meta?: MetaInfo) => Partial<Formatter> | undefined;
47
+ /**
48
+ * Loads a GraphQL schema from the specified location using configured document loaders.
49
+ *
50
+ * @param schemaLocation - The location/path of the GraphQL schema to load (e.g., file path, URL, or glob pattern).
51
+ * @param loadersList - Optional loader configuration for customizing how the schema is loaded.
52
+ *
53
+ * @returns A promise that resolves to the loaded GraphQL schema, or undefined if:
54
+ * - The loaders cannot be initialized
55
+ * - An error occurs during schema loading
56
+ *
57
+ * @internal
58
+ */
59
+ export declare const loadGraphqlSchema: (schemaLocation: string, loadersList: Maybe<LoaderOption>) => Promise<Maybe<GraphQLSchema>>;
60
+ /**
61
+ * Checks if there are differences in the GraphQL schema compared to a previous version.
62
+ *
63
+ * @param schema - The GraphQL schema to check for differences.
64
+ * @param schemaLocation - The location/path of the schema file for logging purposes.
65
+ * @param diffMethod - The method to use for detecting differences. If set to `NONE`, changes detection is skipped.
66
+ * @param tmpDir - The temporary directory path used for storing and comparing schema versions.
67
+ *
68
+ * @returns A promise that resolves to `true` if changes are detected or if diff method is `NONE`,
69
+ * or `false` if no changes are detected.
70
+ *
71
+ * @remarks
72
+ * When no changes are detected, a log message is generated indicating that the schema is unchanged.
73
+ */
74
+ export declare const checkSchemaDifferences: (schema: GraphQLSchema, schemaLocation: string, diffMethod: Maybe<TypeDiffMethod>, tmpDir: string) => Promise<boolean>;
75
+ /**
76
+ * Resolves and retrieves GraphQL directive objects from the schema based on their names.
77
+ *
78
+ * Takes two lists of directive names (for "only" and "skip" documentation directives),
79
+ * looks them up in the provided GraphQL schema, and returns the resolved directive objects.
80
+ *
81
+ * @param onlyDocDirective - A directive name or array of directive names for "only" documentation filtering
82
+ * @param skipDocDirective - A directive name or array of directive names for "skip" documentation filtering
83
+ * @param schema - The GraphQL schema to resolve directives from
84
+ *
85
+ * @returns A tuple containing two arrays: the first with resolved "only" directives,
86
+ * the second with resolved "skip" directives. Only defined directives are included.
87
+ */
88
+ export declare const resolveSkipAndOnlyDirectives: (onlyDocDirective: Maybe<DirectiveName[] | DirectiveName>, skipDocDirective: Maybe<DirectiveName[] | DirectiveName>, schema: GraphQLSchema) => GraphQLDirective[][];
11
89
  /**
12
90
  * Main entry point for generating Markdown documentation from a GraphQL schema.
13
91
  *
@@ -1 +1 @@
1
- {"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAGV,gBAAgB,EAKjB,MAAM,yBAAyB,CAAC;AA6CjC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,qUAwMjC,CAAC"}
1
+ {"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAEV,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,WAAW,EAEX,cAAc,EAEf,MAAM,yBAAyB,CAAC;AA+BjC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAgBX;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,8DAYzB,CAAC;AAgBF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,yEAkDrC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,6FAe7B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,wHAgBlC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,qKA0BxC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,qUAsNjC,CAAC"}
package/dist/generator.js CHANGED
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.generateDocFromSchema = void 0;
36
+ exports.generateDocFromSchema = exports.resolveSkipAndOnlyDirectives = exports.checkSchemaDifferences = exports.loadGraphqlSchema = exports.getFormatterFromMDXModule = exports.loadMDXModule = exports.FILE_EXTENSION = void 0;
37
37
  const logger_1 = __importStar(require("@graphql-markdown/logger"));
38
38
  const graphql_1 = require("@graphql-markdown/graphql");
39
39
  const utils_1 = require("@graphql-markdown/utils");
@@ -44,6 +44,17 @@ const renderer_1 = require("./renderer");
44
44
  const event_emitter_1 = require("./event-emitter");
45
45
  const events_1 = require("./events");
46
46
  const event_handlers_1 = require("./event-handlers");
47
+ /**
48
+ * Supported file extensions for generated documentation files.
49
+ *
50
+ * @remarks
51
+ * - MDX: MDX file extension (.mdx) for React component-enabled markdown
52
+ * - MD: Standard markdown file extension (.md)
53
+ */
54
+ exports.FILE_EXTENSION = {
55
+ MDX: ".mdx",
56
+ MD: ".md",
57
+ };
47
58
  /**
48
59
  * Constant representing nanoseconds per second.
49
60
  *
@@ -58,56 +69,158 @@ const NS_PER_SEC = 1e9;
58
69
  */
59
70
  const SEC_DECIMALS = 3;
60
71
  /**
61
- * Main entry point for generating Markdown documentation from a GraphQL schema.
72
+ * Asynchronously loads an MDX module dynamically.
62
73
  *
63
- * This function coordinates the entire documentation generation process:
64
- * - Loads and validates the schema
65
- * - Checks for schema changes if diffing is enabled
66
- * - Processes directives and groups
67
- * - Initializes printers and renderers
68
- * - Generates markdown files
74
+ * @param mdxParser - The MDX parser package name or path to import. Can be null or undefined.
75
+ * @returns A promise that resolves to the imported module, or undefined if:
76
+ * - The mdxParser parameter is null or undefined
77
+ * - An error occurs during import (logs a warning and returns undefined)
69
78
  *
70
- * @param options - Complete configuration for the documentation generation
71
- * @returns Promise that resolves when documentation is fully generated
79
+ * @internal
72
80
  */
73
- 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, }) => {
74
- const start = process.hrtime.bigint();
75
- await (0, logger_1.default)(loggerModule);
81
+ const loadMDXModule = async (mdxParser) => {
82
+ return mdxParser !== undefined && mdxParser !== null
83
+ ? Promise.resolve(`${mdxParser}`).then(s => __importStar(require(s))).catch(() => {
84
+ (0, logger_1.log)(`An error occurred while loading MDX formatter "${mdxParser}"`, logger_1.LogLevel.warn);
85
+ return undefined;
86
+ })
87
+ : undefined;
88
+ };
89
+ exports.loadMDXModule = loadMDXModule;
90
+ /**
91
+ * List of formatter function names that can be exported individually from an MDX module.
92
+ */
93
+ const FORMATTER_FUNCTION_NAMES = [
94
+ "formatMDXBadge",
95
+ "formatMDXAdmonition",
96
+ "formatMDXBullet",
97
+ "formatMDXDetails",
98
+ "formatMDXFrontmatter",
99
+ "formatMDXLink",
100
+ "formatMDXNameEntity",
101
+ "formatMDXSpecifiedByLink",
102
+ ];
103
+ /**
104
+ * Extracts a formatter from an MDX module.
105
+ *
106
+ * Checks for formatter functions in the following order:
107
+ * 1. A `createMDXFormatter` factory function (for internal/advanced usage)
108
+ * 2. Individual exported formatter functions (e.g., `formatMDXBadge`, `formatMDXAdmonition`)
109
+ *
110
+ * @param mdxModule - The loaded MDX module that may contain formatter exports
111
+ * @param meta - Optional metadata to pass to the formatter factory
112
+ * @returns A partial Formatter with the found functions, or undefined if none found
113
+ *
114
+ * @internal
115
+ */
116
+ const getFormatterFromMDXModule = (mdxModule, meta) => {
117
+ if (!mdxModule || typeof mdxModule !== "object") {
118
+ return undefined;
119
+ }
120
+ const module = mdxModule;
121
+ // Check for createMDXFormatter on the module directly (internal/advanced usage)
122
+ if ("createMDXFormatter" in module &&
123
+ typeof module.createMDXFormatter === "function") {
124
+ return module.createMDXFormatter(meta);
125
+ }
126
+ // Check for createMDXFormatter on module.default (ESM default export)
127
+ const defaultExport = module.default;
128
+ if (defaultExport &&
129
+ "createMDXFormatter" in defaultExport &&
130
+ typeof defaultExport.createMDXFormatter === "function") {
131
+ return defaultExport.createMDXFormatter(meta);
132
+ }
133
+ // Check for individual formatter functions
134
+ const formatter = {};
135
+ let hasFormatter = false;
136
+ for (const funcName of FORMATTER_FUNCTION_NAMES) {
137
+ if (funcName in module && typeof module[funcName] === "function") {
138
+ formatter[funcName] = module[funcName];
139
+ hasFormatter = true;
140
+ }
141
+ else if (defaultExport &&
142
+ funcName in defaultExport &&
143
+ typeof defaultExport[funcName] === "function") {
144
+ formatter[funcName] =
145
+ defaultExport[funcName];
146
+ hasFormatter = true;
147
+ }
148
+ }
149
+ return hasFormatter ? formatter : undefined;
150
+ };
151
+ exports.getFormatterFromMDXModule = getFormatterFromMDXModule;
152
+ /**
153
+ * Loads a GraphQL schema from the specified location using configured document loaders.
154
+ *
155
+ * @param schemaLocation - The location/path of the GraphQL schema to load (e.g., file path, URL, or glob pattern).
156
+ * @param loadersList - Optional loader configuration for customizing how the schema is loaded.
157
+ *
158
+ * @returns A promise that resolves to the loaded GraphQL schema, or undefined if:
159
+ * - The loaders cannot be initialized
160
+ * - An error occurs during schema loading
161
+ *
162
+ * @internal
163
+ */
164
+ const loadGraphqlSchema = async (schemaLocation, loadersList) => {
76
165
  const loaders = await (0, graphql_1.getDocumentLoaders)(loadersList);
77
166
  if (!loaders) {
78
167
  (0, logger_1.log)(`An error occurred while loading GraphQL loader.\nCheck your dependencies and configuration.`, "error");
79
- return;
168
+ return undefined;
80
169
  }
81
- const events = (0, event_emitter_1.getEvents)();
82
- const beforeLoadEvent = new events_1.SchemaLoadEvent({
83
- schemaLocation: schemaLocation,
84
- });
85
- await events.emitAsync(events_1.SchemaEvents.BEFORE_LOAD, beforeLoadEvent);
86
- const schema = await (0, graphql_1.loadSchema)(schemaLocation, loaders);
87
- const afterLoadEvent = new events_1.SchemaLoadEvent({
88
- schemaLocation: schemaLocation,
89
- });
90
- await events.emitAsync(events_1.SchemaEvents.AFTER_LOAD, afterLoadEvent);
170
+ return (0, graphql_1.loadSchema)(schemaLocation, loaders);
171
+ };
172
+ exports.loadGraphqlSchema = loadGraphqlSchema;
173
+ /**
174
+ * Checks if there are differences in the GraphQL schema compared to a previous version.
175
+ *
176
+ * @param schema - The GraphQL schema to check for differences.
177
+ * @param schemaLocation - The location/path of the schema file for logging purposes.
178
+ * @param diffMethod - The method to use for detecting differences. If set to `NONE`, changes detection is skipped.
179
+ * @param tmpDir - The temporary directory path used for storing and comparing schema versions.
180
+ *
181
+ * @returns A promise that resolves to `true` if changes are detected or if diff method is `NONE`,
182
+ * or `false` if no changes are detected.
183
+ *
184
+ * @remarks
185
+ * When no changes are detected, a log message is generated indicating that the schema is unchanged.
186
+ */
187
+ const checkSchemaDifferences = async (schema, schemaLocation, diffMethod, tmpDir) => {
188
+ let changed = true;
91
189
  if (diffMethod !== config_1.DiffMethod.NONE) {
92
- const beforeDiffEvent = new events_1.DiffCheckEvent({
93
- schema,
94
- outputDir: tmpDir,
95
- });
96
- await events.emitAsync(events_1.DiffEvents.BEFORE_CHECK, beforeDiffEvent);
97
- const changed = await (0, diff_1.hasChanges)(schema, tmpDir, diffMethod);
190
+ changed = await (0, diff_1.hasChanges)(schema, tmpDir, diffMethod);
98
191
  if (!changed) {
99
192
  (0, logger_1.log)(`No changes detected in schema "${(0, utils_1.toString)(schemaLocation)}".`);
100
193
  }
101
- const afterDiffEvent = new events_1.DiffCheckEvent({
102
- schema,
103
- outputDir: tmpDir,
104
- });
105
- await events.emitAsync(events_1.DiffEvents.AFTER_CHECK, afterDiffEvent);
106
194
  }
107
- const [onlyDocDirectives, skipDocDirectives] = [
108
- onlyDocDirective,
109
- skipDocDirective,
110
- ].map((directiveList) => {
195
+ return changed;
196
+ };
197
+ exports.checkSchemaDifferences = checkSchemaDifferences;
198
+ /**
199
+ * Resolves and retrieves GraphQL directive objects from the schema based on their names.
200
+ *
201
+ * Takes two lists of directive names (for "only" and "skip" documentation directives),
202
+ * looks them up in the provided GraphQL schema, and returns the resolved directive objects.
203
+ *
204
+ * @param onlyDocDirective - A directive name or array of directive names for "only" documentation filtering
205
+ * @param skipDocDirective - A directive name or array of directive names for "skip" documentation filtering
206
+ * @param schema - The GraphQL schema to resolve directives from
207
+ *
208
+ * @returns A tuple containing two arrays: the first with resolved "only" directives,
209
+ * the second with resolved "skip" directives. Only defined directives are included.
210
+ */
211
+ const resolveSkipAndOnlyDirectives = (onlyDocDirective, skipDocDirective, schema) => {
212
+ return [onlyDocDirective, skipDocDirective].map((directive) => {
213
+ // Normalize to array and filter out null/undefined
214
+ let directiveList;
215
+ if (Array.isArray(directive)) {
216
+ directiveList = directive;
217
+ }
218
+ else if (directive) {
219
+ directiveList = [directive];
220
+ }
221
+ else {
222
+ directiveList = [];
223
+ }
111
224
  return directiveList
112
225
  .map((name) => {
113
226
  return schema.getDirective(name);
@@ -116,17 +229,58 @@ const generateDocFromSchema = async ({ baseURL, customDirective, diffMethod, doc
116
229
  return directive !== undefined;
117
230
  });
118
231
  });
232
+ };
233
+ exports.resolveSkipAndOnlyDirectives = resolveSkipAndOnlyDirectives;
234
+ /**
235
+ * Main entry point for generating Markdown documentation from a GraphQL schema.
236
+ *
237
+ * This function coordinates the entire documentation generation process:
238
+ * - Loads and validates the schema
239
+ * - Checks for schema changes if diffing is enabled
240
+ * - Processes directives and groups
241
+ * - Initializes printers and renderers
242
+ * - Generates markdown files
243
+ *
244
+ * @param options - Complete configuration for the documentation generation
245
+ * @returns Promise that resolves when documentation is fully generated
246
+ */
247
+ 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, }) => {
248
+ const start = process.hrtime.bigint();
249
+ const events = (0, event_emitter_1.getEvents)();
250
+ await (0, logger_1.default)(loggerModule);
251
+ const mdxModule = await (0, exports.loadMDXModule)(mdxParser);
252
+ // Register MDX lifecycle event handlers if mdxModule loaded successfully
253
+ (0, event_handlers_1.registerMDXEventHandlers)(mdxModule);
254
+ await events.emitAsync(events_1.SchemaEvents.BEFORE_LOAD, new events_1.SchemaEvent({
255
+ schemaLocation: schemaLocation,
256
+ }));
257
+ const schema = await (0, exports.loadGraphqlSchema)(schemaLocation, loadersList);
258
+ await events.emitAsync(events_1.SchemaEvents.AFTER_LOAD, new events_1.SchemaEvent({
259
+ schemaLocation: schemaLocation,
260
+ schema,
261
+ }));
262
+ if (!schema) {
263
+ (0, logger_1.log)(`Failed to load GraphQL schema from location "${(0, utils_1.toString)(schemaLocation)}".`, "error");
264
+ return;
265
+ }
266
+ await events.emitAsync(events_1.DiffEvents.BEFORE_CHECK, new events_1.DiffCheckEvent({
267
+ schema,
268
+ outputDir: tmpDir,
269
+ }));
270
+ const schemaHasChanges = await (0, exports.checkSchemaDifferences)(schema, schemaLocation, diffMethod, tmpDir);
271
+ await events.emitAsync(events_1.DiffEvents.AFTER_CHECK, new events_1.DiffCheckEvent({ schemaHasChanges }));
272
+ const [onlyDocDirectives, skipDocDirectives] = (0, exports.resolveSkipAndOnlyDirectives)(onlyDocDirective, skipDocDirective, schema);
273
+ events.emit(events_1.SchemaEvents.BEFORE_MAP, new events_1.SchemaEvent({ schema }));
119
274
  const rootTypes = (0, graphql_1.getSchemaMap)(schema);
275
+ events.emit(events_1.SchemaEvents.AFTER_MAP, new events_1.SchemaEvent({ schema, rootTypes }));
120
276
  const customDirectives = (0, graphql_1.getCustomDirectives)(rootTypes, customDirective);
121
277
  const groups = (0, graphql_1.getGroups)(rootTypes, groupByDirective);
122
- const mdxModule = await (mdxParser !== undefined && mdxParser !== null
123
- ? Promise.resolve(`${mdxParser}`).then(s => __importStar(require(s))).catch(() => {
124
- (0, logger_1.log)(`An error occurred while loading MDX formatter "${mdxParser}"`, logger_1.LogLevel.warn);
125
- return undefined;
126
- })
127
- : undefined);
128
- // Register MDX event handlers if mdxModule loaded successfully
129
- (0, event_handlers_1.registerMDXEventHandlers)(mdxModule);
278
+ // Extract formatter from the MDX module (for direct function calls)
279
+ const formatter = (0, exports.getFormatterFromMDXModule)(mdxModule, docOptions);
280
+ // Extract mdxDeclaration from the MDX module (if available)
281
+ const mdxDeclaration = mdxModule && typeof mdxModule === "object" && "mdxDeclaration" in mdxModule
282
+ ? mdxModule.mdxDeclaration
283
+ : undefined;
130
284
  const printer = await (0, printer_1.getPrinter)(
131
285
  // module mandatory
132
286
  printerModule,
@@ -148,13 +302,27 @@ const generateDocFromSchema = async ({ baseURL, customDirective, diffMethod, doc
148
302
  onlyDocDirectives,
149
303
  printTypeOptions,
150
304
  skipDocDirectives,
151
- }, mdxModule);
305
+ }, formatter, mdxDeclaration);
306
+ // allow mdxModule to specify custom extension
307
+ let mdxExtension;
308
+ if (mdxModule &&
309
+ typeof mdxModule === "object" &&
310
+ "mdxExtension" in mdxModule) {
311
+ mdxExtension = mdxModule
312
+ .mdxExtension;
313
+ }
314
+ else if (mdxModule) {
315
+ mdxExtension = exports.FILE_EXTENSION.MDX;
316
+ }
317
+ else {
318
+ mdxExtension = exports.FILE_EXTENSION.MD;
319
+ }
152
320
  const renderer = await (0, renderer_1.getRenderer)(printer, outputDir, baseURL, groups, prettify, {
153
321
  ...docOptions,
154
322
  deprecated: printTypeOptions?.deprecated,
155
323
  force,
156
324
  hierarchy: printTypeOptions?.hierarchy,
157
- }, mdxModule);
325
+ }, mdxExtension);
158
326
  // Pre-collect all categories before rendering to ensure consistent positions
159
327
  renderer.preCollectCategories(Object.keys(rootTypes));
160
328
  const beforeRenderRootTypesEvent = new events_1.RenderRootTypesEvent({
package/dist/index.d.ts CHANGED
@@ -6,8 +6,14 @@ export { buildConfig } from "./config";
6
6
  export { getEvents, resetEvents, type EmitResult } from "./event-emitter";
7
7
  export { registerMDXEventHandlers } from "./event-handlers";
8
8
  export { EVENT_CALLBACK_MAP } from "./event-map";
9
+ export { SchemaEvents } from "./events/schema-events";
10
+ export { DiffEvents } from "./events/diff-events";
11
+ export { RenderRootTypesEvents } from "./events/render-root-types-events";
12
+ export { RenderHomepageEvents } from "./events/render-homepage-events";
13
+ export { RenderTypeEntitiesEvents } from "./events/render-type-entities-events";
14
+ export { GenerateIndexMetafileEvents } from "./events/generate-index-metafile-events";
9
15
  export type { CancellableEvent } from "./events/base";
10
- export type { SchemaLoadEvent } from "./events/schema-load";
16
+ export type { SchemaEvent as SchemaLoadEvent } from "./events/schema-load";
11
17
  export type { DiffCheckEvent } from "./events/diff-check";
12
18
  export type { RenderRootTypesEvent } from "./events/render-root-types";
13
19
  export type { RenderHomepageEvent } from "./events/render-homepage";
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,MAAM,yCAAyC,CAAC;AAGtF,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC"}
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@
4
4
  */
5
5
  /* istanbul ignore file */
6
6
  Object.defineProperty(exports, "__esModule", { value: true });
7
- exports.EVENT_CALLBACK_MAP = exports.registerMDXEventHandlers = exports.resetEvents = exports.getEvents = exports.buildConfig = exports.generateDocFromSchema = void 0;
7
+ exports.GenerateIndexMetafileEvents = exports.RenderTypeEntitiesEvents = exports.RenderHomepageEvents = exports.RenderRootTypesEvents = exports.DiffEvents = exports.SchemaEvents = exports.EVENT_CALLBACK_MAP = exports.registerMDXEventHandlers = exports.resetEvents = exports.getEvents = exports.buildConfig = exports.generateDocFromSchema = void 0;
8
8
  const generator_1 = require("./generator");
9
9
  Object.defineProperty(exports, "generateDocFromSchema", { enumerable: true, get: function () { return generator_1.generateDocFromSchema; } });
10
10
  const config_1 = require("./config");
@@ -17,3 +17,16 @@ const event_handlers_1 = require("./event-handlers");
17
17
  Object.defineProperty(exports, "registerMDXEventHandlers", { enumerable: true, get: function () { return event_handlers_1.registerMDXEventHandlers; } });
18
18
  const event_map_1 = require("./event-map");
19
19
  Object.defineProperty(exports, "EVENT_CALLBACK_MAP", { enumerable: true, get: function () { return event_map_1.EVENT_CALLBACK_MAP; } });
20
+ // Event constant exports
21
+ const schema_events_1 = require("./events/schema-events");
22
+ Object.defineProperty(exports, "SchemaEvents", { enumerable: true, get: function () { return schema_events_1.SchemaEvents; } });
23
+ const diff_events_1 = require("./events/diff-events");
24
+ Object.defineProperty(exports, "DiffEvents", { enumerable: true, get: function () { return diff_events_1.DiffEvents; } });
25
+ const render_root_types_events_1 = require("./events/render-root-types-events");
26
+ Object.defineProperty(exports, "RenderRootTypesEvents", { enumerable: true, get: function () { return render_root_types_events_1.RenderRootTypesEvents; } });
27
+ const render_homepage_events_1 = require("./events/render-homepage-events");
28
+ Object.defineProperty(exports, "RenderHomepageEvents", { enumerable: true, get: function () { return render_homepage_events_1.RenderHomepageEvents; } });
29
+ const render_type_entities_events_1 = require("./events/render-type-entities-events");
30
+ Object.defineProperty(exports, "RenderTypeEntitiesEvents", { enumerable: true, get: function () { return render_type_entities_events_1.RenderTypeEntitiesEvents; } });
31
+ const generate_index_metafile_events_1 = require("./events/generate-index-metafile-events");
32
+ Object.defineProperty(exports, "GenerateIndexMetafileEvents", { enumerable: true, get: function () { return generate_index_metafile_events_1.GenerateIndexMetafileEvents; } });