@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.
@@ -1,10 +1,93 @@
1
+ /**
2
+ * GraphQL Markdown configuration utilities
3
+ *
4
+ * This module provides utilities for loading and processing GraphQL configuration
5
+ * using the graphql-config package.
6
+ *
7
+ * @module graphql-config
8
+ */
1
9
  import type { ExtensionProjectConfig, GraphQLExtensionDeclaration, LoaderOption, Maybe, PackageOptionsConfig } from "@graphql-markdown/types";
10
+ /**
11
+ * The name of the GraphQL Markdown extension.
12
+ * Used to identify the extension in graphql-config.
13
+ */
2
14
  export declare const EXTENSION_NAME: "graphql-markdown";
15
+ /**
16
+ * GraphQL extension declaration for graphql-config.
17
+ *
18
+ * @returns The extension configuration object with name property.
19
+ *
20
+ * @example
21
+ * ```typescript
22
+ * // In graphql-config setup
23
+ * const config = await loadConfig({
24
+ * extensions: [graphQLConfigExtension],
25
+ * });
26
+ * ```
27
+ */
3
28
  export declare const graphQLConfigExtension: GraphQLExtensionDeclaration;
29
+ /**
30
+ * Options for controlling throw behavior when loading configuration.
31
+ *
32
+ * @interface ThrowOptions
33
+ * @property throwOnMissing Whether to throw when the config file is missing.
34
+ * @property throwOnEmpty Whether to throw when the config is empty.
35
+ */
4
36
  interface ThrowOptions {
5
- throwOnMissing: boolean;
6
- throwOnEmpty: boolean;
37
+ throwOnMissing?: boolean;
38
+ throwOnEmpty?: boolean;
7
39
  }
40
+ /**
41
+ * Sets loader options for GraphQL Markdown loaders.
42
+ *
43
+ * This function takes a LoaderOption object and merges the provided options
44
+ * with any existing options for each loader.
45
+ *
46
+ * @param loaders - The loader configuration object.
47
+ * @param options - The package options to apply to loaders.
48
+ * @returns The updated loader configuration.
49
+ *
50
+ * @example
51
+ * ```typescript
52
+ * const loaders = {
53
+ * TypeScriptLoader: {
54
+ * module: "@graphql-markdown/typescript-loader",
55
+ * options: { baseDir: "./src" }
56
+ * }
57
+ * };
58
+ * const options = { outputDir: "./docs" };
59
+ * const updatedLoaders = setLoaderOptions(loaders, options);
60
+ * // Result: loaders with { baseDir: "./src", outputDir: "./docs" }
61
+ * ```
62
+ */
8
63
  export declare const setLoaderOptions: (loaders: LoaderOption, options: PackageOptionsConfig) => LoaderOption;
64
+ /**
65
+ * Loads the GraphQL Markdown configuration from graphql-config.
66
+ *
67
+ * This function attempts to load the GraphQL config and extract the
68
+ * GraphQL Markdown extension configuration for the specified project ID.
69
+ * It also normalizes schema configurations.
70
+ *
71
+ * @param id - The project ID to load configuration for.
72
+ * @param options - Optional package options to apply.
73
+ * @param throwOptions - Options for controlling throw behavior.
74
+ * @returns The extension project configuration if found, otherwise undefined.
75
+ *
76
+ * @throws Will throw an error if throwOnMissing or throwOnEmpty is true and
77
+ * the corresponding condition is met.
78
+ *
79
+ * @example
80
+ * ```typescript
81
+ * // Basic usage
82
+ * const config = await loadConfiguration("my-project");
83
+ *
84
+ * // With options and throw behavior
85
+ * const config = await loadConfiguration(
86
+ * "my-project",
87
+ * { baseDir: "./src" },
88
+ * { throwOnMissing: true, throwOnEmpty: false }
89
+ * );
90
+ * ```
91
+ */
9
92
  export declare const loadConfiguration: (id: Maybe<string>, options?: Maybe<PackageOptionsConfig>, { throwOnMissing, throwOnEmpty }?: ThrowOptions) => Promise<Maybe<Readonly<ExtensionProjectConfig>>>;
10
93
  export {};
@@ -35,11 +35,51 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.loadConfiguration = exports.setLoaderOptions = exports.graphQLConfigExtension = exports.EXTENSION_NAME = void 0;
37
37
  const logger_1 = require("@graphql-markdown/logger");
38
+ /**
39
+ * The name of the GraphQL Markdown extension.
40
+ * Used to identify the extension in graphql-config.
41
+ */
38
42
  exports.EXTENSION_NAME = "graphql-markdown";
43
+ /**
44
+ * GraphQL extension declaration for graphql-config.
45
+ *
46
+ * @returns The extension configuration object with name property.
47
+ *
48
+ * @example
49
+ * ```typescript
50
+ * // In graphql-config setup
51
+ * const config = await loadConfig({
52
+ * extensions: [graphQLConfigExtension],
53
+ * });
54
+ * ```
55
+ */
39
56
  const graphQLConfigExtension = () => {
40
57
  return { name: exports.EXTENSION_NAME };
41
58
  };
42
59
  exports.graphQLConfigExtension = graphQLConfigExtension;
60
+ /**
61
+ * Sets loader options for GraphQL Markdown loaders.
62
+ *
63
+ * This function takes a LoaderOption object and merges the provided options
64
+ * with any existing options for each loader.
65
+ *
66
+ * @param loaders - The loader configuration object.
67
+ * @param options - The package options to apply to loaders.
68
+ * @returns The updated loader configuration.
69
+ *
70
+ * @example
71
+ * ```typescript
72
+ * const loaders = {
73
+ * TypeScriptLoader: {
74
+ * module: "@graphql-markdown/typescript-loader",
75
+ * options: { baseDir: "./src" }
76
+ * }
77
+ * };
78
+ * const options = { outputDir: "./docs" };
79
+ * const updatedLoaders = setLoaderOptions(loaders, options);
80
+ * // Result: loaders with { baseDir: "./src", outputDir: "./docs" }
81
+ * ```
82
+ */
43
83
  const setLoaderOptions = (loaders, options) => {
44
84
  for (const loader in loaders) {
45
85
  if (typeof loaders[loader] === "string") {
@@ -58,6 +98,34 @@ const setLoaderOptions = (loaders, options) => {
58
98
  return loaders;
59
99
  };
60
100
  exports.setLoaderOptions = setLoaderOptions;
101
+ /**
102
+ * Loads the GraphQL Markdown configuration from graphql-config.
103
+ *
104
+ * This function attempts to load the GraphQL config and extract the
105
+ * GraphQL Markdown extension configuration for the specified project ID.
106
+ * It also normalizes schema configurations.
107
+ *
108
+ * @param id - The project ID to load configuration for.
109
+ * @param options - Optional package options to apply.
110
+ * @param throwOptions - Options for controlling throw behavior.
111
+ * @returns The extension project configuration if found, otherwise undefined.
112
+ *
113
+ * @throws Will throw an error if throwOnMissing or throwOnEmpty is true and
114
+ * the corresponding condition is met.
115
+ *
116
+ * @example
117
+ * ```typescript
118
+ * // Basic usage
119
+ * const config = await loadConfiguration("my-project");
120
+ *
121
+ * // With options and throw behavior
122
+ * const config = await loadConfiguration(
123
+ * "my-project",
124
+ * { baseDir: "./src" },
125
+ * { throwOnMissing: true, throwOnEmpty: false }
126
+ * );
127
+ * ```
128
+ */
61
129
  const loadConfiguration = async (id, options, { throwOnMissing, throwOnEmpty } = {
62
130
  throwOnMissing: false,
63
131
  throwOnEmpty: false,
package/dist/index.d.ts CHANGED
@@ -1,2 +1,5 @@
1
+ /**
2
+ * @primaryExport
3
+ */
1
4
  export { generateDocFromSchema } from "./generator";
2
5
  export { buildConfig } from "./config";
package/dist/index.js CHANGED
@@ -1,4 +1,7 @@
1
1
  "use strict";
2
+ /**
3
+ * @primaryExport
4
+ */
2
5
  /* istanbul ignore file */
3
6
  Object.defineProperty(exports, "__esModule", { value: true });
4
7
  exports.buildConfig = exports.generateDocFromSchema = void 0;
package/dist/printer.d.ts CHANGED
@@ -1,2 +1,52 @@
1
+ /**
2
+ * @module printer
3
+ *
4
+ * This module provides the functionality to load and initialize a printer for GraphQL schema documentation.
5
+ * It dynamically imports a printer module and configures it with the provided schema and options.
6
+ */
1
7
  import type { Maybe, PackageName, Printer, PrinterConfig, PrinterOptions } from "@graphql-markdown/types";
8
+ /**
9
+ * Loads and initializes a printer module for GraphQL schema documentation.
10
+ *
11
+ * This function dynamically imports the specified printer module and initializes it
12
+ * with the provided configuration and options. The printer is responsible for rendering
13
+ * GraphQL schema documentation in the desired format.
14
+ *
15
+ * @param printerModule - The name/path of the printer module to load
16
+ * @param config - Configuration for the printer including schema, baseURL, and linkRoot
17
+ * @param options - Additional options for customizing the printer's behavior
18
+ * @param mdxModule - Optional MDX module for MDX-specific functionality
19
+ *
20
+ * @returns A promise that resolves to the initialized Printer instance
21
+ *
22
+ * @throws Will throw an error if printerModule is not a string
23
+ * @throws Will throw an error if config is not provided
24
+ * @throws Will throw an error if the module specified by printerModule cannot be found
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * import { getPrinter } from '@graphql-markdown/core';
29
+ * import { buildSchema } from 'graphql';
30
+ *
31
+ * const schema = buildSchema(`
32
+ * type Query {
33
+ * hello: String
34
+ * }
35
+ * `);
36
+ *
37
+ * const printer = await getPrinter(
38
+ * '@graphql-markdown/printer-legacy',
39
+ * {
40
+ * schema,
41
+ * baseURL: '/docs',
42
+ * linkRoot: 'graphql'
43
+ * },
44
+ * {
45
+ * printTypeOptions: { includeDeprecationReasons: true }
46
+ * }
47
+ * );
48
+ *
49
+ * const output = printer.printSchema();
50
+ * ```
51
+ */
2
52
  export declare const getPrinter: (printerModule?: Maybe<PackageName>, config?: Maybe<PrinterConfig>, options?: Maybe<PrinterOptions>, mdxModule?: unknown) => Promise<Printer>;
package/dist/printer.js CHANGED
@@ -34,6 +34,50 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.getPrinter = void 0;
37
+ /**
38
+ * Loads and initializes a printer module for GraphQL schema documentation.
39
+ *
40
+ * This function dynamically imports the specified printer module and initializes it
41
+ * with the provided configuration and options. The printer is responsible for rendering
42
+ * GraphQL schema documentation in the desired format.
43
+ *
44
+ * @param printerModule - The name/path of the printer module to load
45
+ * @param config - Configuration for the printer including schema, baseURL, and linkRoot
46
+ * @param options - Additional options for customizing the printer's behavior
47
+ * @param mdxModule - Optional MDX module for MDX-specific functionality
48
+ *
49
+ * @returns A promise that resolves to the initialized Printer instance
50
+ *
51
+ * @throws Will throw an error if printerModule is not a string
52
+ * @throws Will throw an error if config is not provided
53
+ * @throws Will throw an error if the module specified by printerModule cannot be found
54
+ *
55
+ * @example
56
+ * ```typescript
57
+ * import { getPrinter } from '@graphql-markdown/core';
58
+ * import { buildSchema } from 'graphql';
59
+ *
60
+ * const schema = buildSchema(`
61
+ * type Query {
62
+ * hello: String
63
+ * }
64
+ * `);
65
+ *
66
+ * const printer = await getPrinter(
67
+ * '@graphql-markdown/printer-legacy',
68
+ * {
69
+ * schema,
70
+ * baseURL: '/docs',
71
+ * linkRoot: 'graphql'
72
+ * },
73
+ * {
74
+ * printTypeOptions: { includeDeprecationReasons: true }
75
+ * }
76
+ * );
77
+ *
78
+ * const output = printer.printSchema();
79
+ * ```
80
+ */
37
81
  const getPrinter = async (printerModule, config, options, mdxModule) => {
38
82
  if (typeof printerModule !== "string") {
39
83
  throw new Error("Invalid printer module name.");
@@ -1,12 +1,77 @@
1
1
  import type { ApiGroupOverrideType, Category, Maybe, MDXSupportType, Printer, RendererDocOptions, SchemaEntitiesGroupMap, SchemaEntity } from "@graphql-markdown/types";
2
+ /**
3
+ * Default group names for API types and non-API types.
4
+ * This constant provides the base folder structure for organizing GraphQL schema entities.
5
+ * Can be overridden via ApiGroupOverrideType in configuration.
6
+ *
7
+ * @property operations Folder name for GraphQL operations (queries, mutations, subscriptions)
8
+ * @property types Folder name for GraphQL type definitions
9
+ * @useDeclaredType
10
+ *
11
+ * @example
12
+ * ```typescript
13
+ * // Default structure
14
+ * const defaultGroups = API_GROUPS;
15
+ * // { operations: "operations", types: "types" }
16
+ *
17
+ * // With custom override
18
+ * const customGroups = { ...API_GROUPS, operations: "queries-and-mutations" };
19
+ * ```
20
+ *
21
+ * @see {@link getApiGroupFolder} For usage with type categorization
22
+ */
2
23
  export declare const API_GROUPS: Required<ApiGroupOverrideType>;
24
+ /**
25
+ * Determines the appropriate folder for a GraphQL schema entity based on its type.
26
+ *
27
+ * @param type - The GraphQL schema entity to categorize
28
+ * @param groups - Optional custom group naming configuration
29
+ * @returns The folder name where the entity should be placed
30
+ * @useDeclaredType
31
+ *
32
+ * @example
33
+ * ```typescript
34
+ * // With default groups
35
+ * const folder = getApiGroupFolder(queryType); // Returns "operations"
36
+ *
37
+ * // With custom groups
38
+ * const folder = getApiGroupFolder(objectType, { operations: "queries" }); // Returns appropriate folder
39
+ * ```
40
+ */
3
41
  export declare const getApiGroupFolder: (type: unknown, groups?: Maybe<ApiGroupOverrideType | boolean>) => string;
42
+ /**
43
+ * Configuration options for category metafiles in the documentation.
44
+ * These options control the appearance and behavior of category sections in the sidebar.
45
+ *
46
+ * @interface CategoryMetafileOptions
47
+ * @property [collapsible] - Whether the category should be collapsible in the sidebar
48
+ * @property [collapsed] - Whether the category should be initially collapsed
49
+ * @property [sidebarPosition] - Custom position in the sidebar (lower numbers appear first)
50
+ * @property [styleClass] - CSS class to apply to the category for styling
51
+ * @useDeclaredType
52
+ *
53
+ * @example
54
+ * ```typescript
55
+ * const options: CategoryMetafileOptions = {
56
+ * collapsible: true,
57
+ * collapsed: false,
58
+ * sidebarPosition: SidebarPosition.FIRST,
59
+ * styleClass: CATEGORY_STYLE_CLASS.API
60
+ * };
61
+ * ```
62
+ */
4
63
  export interface CategoryMetafileOptions {
5
64
  collapsible?: boolean;
6
65
  collapsed?: boolean;
7
66
  sidebarPosition?: number;
8
67
  styleClass?: string;
9
68
  }
69
+ /**
70
+ * Core renderer class responsible for generating documentation files from GraphQL schema entities.
71
+ * Handles the conversion of schema types to markdown/MDX documentation with proper organization.
72
+ * @useDeclaredType
73
+ * @example
74
+ */
10
75
  export declare class Renderer {
11
76
  group: Maybe<SchemaEntitiesGroupMap>;
12
77
  outputDir: string;
@@ -16,12 +81,114 @@ export declare class Renderer {
16
81
  mdxModule: unknown;
17
82
  mdxModuleIndexFileSupport: boolean;
18
83
  private readonly printer;
84
+ /**
85
+ * Creates a new Renderer instance.
86
+ *
87
+ * @param printer - The printer instance used to convert GraphQL types to markdown
88
+ * @param outputDir - Directory where documentation will be generated
89
+ * @param baseURL - Base URL for the documentation
90
+ * @param group - Optional grouping configuration for schema entities
91
+ * @param prettify - Whether to format the generated markdown
92
+ * @param docOptions - Additional documentation options
93
+ * @param mdxModule - Optional MDX module for enhanced documentation features
94
+ * @example
95
+ */
19
96
  constructor(printer: Printer, outputDir: string, baseURL: string, group: Maybe<SchemaEntitiesGroupMap>, prettify: boolean, docOptions: Maybe<RendererDocOptions>, mdxModule?: unknown);
97
+ /**
98
+ * Checks if the provided module supports MDX index file generation.
99
+ *
100
+ * @param module - The module to check for MDX support
101
+ * @returns True if the module supports index metafile generation
102
+ * @useDeclaredType
103
+ * @example
104
+ */
20
105
  hasMDXIndexFileSupport(module?: unknown): module is Partial<MDXSupportType> & Pick<MDXSupportType, "generateIndexMetafile">;
106
+ /**
107
+ * Generates an index metafile for a category directory if MDX support is available.
108
+ *
109
+ * @param dirPath - The directory path where the index should be created
110
+ * @param category - The category name
111
+ * @param options - Configuration options for the index
112
+ * @returns Promise that resolves when the index is generated
113
+ * @useDeclaredType
114
+ *
115
+ * @example
116
+ * ```typescript
117
+ * await renderer.generateIndexMetafile('docs/types', 'Types', {
118
+ * collapsible: true,
119
+ * collapsed: false
120
+ * });
121
+ * ```
122
+ */
21
123
  generateIndexMetafile(dirPath: string, category: string, options?: CategoryMetafileOptions): Promise<void>;
124
+ /**
125
+ * Generates the directory path and metafiles for a specific schema entity type.
126
+ * Creates the appropriate directory structure based on configuration options.
127
+ *
128
+ * @param type - The schema entity type
129
+ * @param name - The name of the schema entity
130
+ * @param rootTypeName - The root type name this entity belongs to
131
+ * @returns The generated directory path
132
+ * @useDeclaredType
133
+ * @example
134
+ */
22
135
  generateCategoryMetafileType(type: unknown, name: string, rootTypeName: SchemaEntity): Promise<string>;
136
+ /**
137
+ * Renders all types within a root type category (e.g., all Query types).
138
+ *
139
+ * @param rootTypeName - The name of the root type (e.g., "Query", "Mutation")
140
+ * @param type - The type object containing all entities to render
141
+ * @returns Array of rendered categories or undefined
142
+ * @useDeclaredType
143
+ * @example
144
+ */
23
145
  renderRootTypes(rootTypeName: SchemaEntity, type: unknown): Promise<Maybe<Maybe<Category>[]>>;
146
+ /**
147
+ * Renders documentation for a specific type entity and saves it to a file.
148
+ *
149
+ * @param dirPath - The directory path where the file should be saved
150
+ * @param name - The name of the type entity
151
+ * @param type - The type entity to render
152
+ * @returns The category information for the rendered entity or undefined
153
+ * @useDeclaredType
154
+ * @example
155
+ */
24
156
  renderTypeEntities(dirPath: string, name: string, type: unknown): Promise<Maybe<Category>>;
25
- renderHomepage(homepageLocation: string): Promise<void>;
157
+ /**
158
+ * Renders the homepage for the documentation from a template file.
159
+ * Replaces placeholders in the template with actual values.
160
+ *
161
+ * @param homepageLocation - Path to the homepage template file
162
+ * @returns Promise that resolves when the homepage is rendered
163
+ * @useDeclaredType
164
+ * @example
165
+ */
166
+ renderHomepage(homepageLocation: Maybe<string>): Promise<void>;
26
167
  }
168
+ /**
169
+ * Factory function to create and initialize a Renderer instance.
170
+ * Creates the output directory and returns a configured renderer.
171
+ *
172
+ * @param printer - The printer instance to use for rendering types
173
+ * @param outputDir - The output directory for generated documentation
174
+ * @param baseURL - The base URL for the documentation
175
+ * @param group - Optional grouping configuration
176
+ * @param prettify - Whether to prettify the output markdown
177
+ * @param docOptions - Additional documentation options
178
+ * @param mdxModule - Optional MDX module for enhanced features
179
+ * @returns A configured Renderer instance
180
+ * @useDeclaredType
181
+ *
182
+ * @example
183
+ * ```typescript
184
+ * const renderer = await getRenderer(
185
+ * myPrinter,
186
+ * './docs',
187
+ * '/api',
188
+ * groupConfig,
189
+ * true,
190
+ * { force: true, index: true }
191
+ * );
192
+ * ```
193
+ */
27
194
  export declare const getRenderer: (printer: Printer, outputDir: string, baseURL: string, group: Maybe<SchemaEntitiesGroupMap>, prettify: boolean, docOptions: Maybe<RendererDocOptions>, mdxModule?: unknown) => Promise<InstanceType<typeof Renderer>>;