@graphql-markdown/core 1.1.6 → 1.2.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/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "bugs": {
6
6
  "url": "https://github.com/graphql-markdown/graphql-markdown/issues"
7
7
  },
8
- "version": "1.1.6",
8
+ "version": "1.2.0",
9
9
  "license": "MIT",
10
10
  "main": "src/index.js",
11
11
  "repository": {
@@ -29,11 +29,11 @@
29
29
  "stryker": "stryker run"
30
30
  },
31
31
  "dependencies": {
32
- "@graphql-markdown/utils": "^1.1.3"
32
+ "@graphql-markdown/utils": "^1.2.0"
33
33
  },
34
34
  "peerDependencies": {
35
- "@graphql-markdown/printer-legacy": "^1.1.6",
36
- "@graphql-markdown/diff": "^1.0.5",
35
+ "@graphql-markdown/printer-legacy": "^1.2.0",
36
+ "@graphql-markdown/diff": "^1.0.7",
37
37
  "prettier": "^2.8"
38
38
  },
39
39
  "peerDependenciesMeta": {
@@ -47,6 +47,9 @@
47
47
  "optional": true
48
48
  }
49
49
  },
50
+ "devDependencies": {
51
+ "@graphql-markdown/printer-legacy": "^1.1.3"
52
+ },
50
53
  "directories": {
51
54
  "test": "tests"
52
55
  },
package/src/config.js CHANGED
@@ -1,6 +1,10 @@
1
1
  const { join } = require("path");
2
2
  const { tmpdir } = require("os");
3
3
 
4
+ const {
5
+ object: { hasProperty },
6
+ } = require("@graphql-markdown/utils");
7
+
4
8
  const { parseGroupByOption } = require("./group-info");
5
9
 
6
10
  const PACKAGE_NAME = "@graphql-markdown/docusaurus";
@@ -26,8 +30,9 @@ const DEFAULT_OPTIONS = {
26
30
  parentTypePrefix: true,
27
31
  relatedTypeSection: true,
28
32
  typeBadges: true,
33
+ deprecated: "default",
29
34
  },
30
- skipDocDirective: undefined,
35
+ skipDocDirective: [],
31
36
  };
32
37
 
33
38
  function buildConfig(configFileOpts, cliOpts) {
@@ -58,9 +63,7 @@ function buildConfig(configFileOpts, cliOpts) {
58
63
  docOptions: getDocOptions(cliOpts, config.docOptions),
59
64
  printTypeOptions: gePrintTypeOptions(cliOpts, config.printTypeOptions),
60
65
  printer: config.printer,
61
- skipDocDirective: getSkipDocDirective(
62
- cliOpts.skip ?? config.skipDocDirective,
63
- ),
66
+ skipDocDirective: getSkipDocDirectives(cliOpts, config),
64
67
  };
65
68
  }
66
69
 
@@ -82,14 +85,39 @@ function gePrintTypeOptions(cliOpts, configOptions) {
82
85
  relatedTypeSection:
83
86
  !cliOpts.noRelatedType && configOptions.relatedTypeSection,
84
87
  typeBadges: !cliOpts.noTypeBadges && configOptions.typeBadges,
88
+ deprecated:
89
+ cliOpts.deprecated ??
90
+ configOptions.deprecated ??
91
+ DEFAULT_OPTIONS.printTypeOptions.deprecated,
85
92
  };
86
93
  }
87
94
 
95
+ function getSkipDocDirectives(cliOpts = {}, configFileOpts = {}) {
96
+ const directiveList = [].concat(
97
+ cliOpts.skip ?? [],
98
+ configFileOpts.skipDocDirective ?? [],
99
+ );
100
+
101
+ const skipDirectives = directiveList.map((option) =>
102
+ getSkipDocDirective(option),
103
+ );
104
+
105
+ if (
106
+ (hasProperty(configFileOpts, "printTypeOptions") &&
107
+ configFileOpts.printTypeOptions.deprecated === "skip") ||
108
+ (hasProperty(cliOpts, "deprecated") && cliOpts.deprecated === "skip")
109
+ ) {
110
+ skipDirectives.push("deprecated");
111
+ }
112
+
113
+ return skipDirectives;
114
+ }
115
+
88
116
  function getSkipDocDirective(option) {
89
117
  const OPTION_REGEX = /^@(?<directive>\w+)$/;
90
118
 
91
119
  if (typeof option !== "string") {
92
- return undefined;
120
+ throw new Error(`Invalid "${option}"`);
93
121
  }
94
122
 
95
123
  const parsedOption = OPTION_REGEX.exec(option);
@@ -101,4 +129,10 @@ function getSkipDocDirective(option) {
101
129
  return parsedOption.groups.directive;
102
130
  }
103
131
 
104
- module.exports = { buildConfig, DEFAULT_OPTIONS, ASSETS_LOCATION };
132
+ module.exports = {
133
+ buildConfig,
134
+ getSkipDocDirectives,
135
+ getSkipDocDirective,
136
+ DEFAULT_OPTIONS,
137
+ ASSETS_LOCATION,
138
+ };
package/src/generator.js CHANGED
@@ -4,7 +4,8 @@ const {
4
4
  const { getGroups } = require("./group-info");
5
5
  const Renderer = require("./renderer");
6
6
 
7
- const time = process.hrtime();
7
+ const NS_PER_SEC = 1e9;
8
+ const SEC_DECIMALS = 3;
8
9
 
9
10
  const hasChanges = async (
10
11
  schema,
@@ -12,7 +13,12 @@ const hasChanges = async (
12
13
  diffMethod,
13
14
  diffModule = "@graphql-markdown/diff",
14
15
  ) => {
15
- if (typeof diffMethod === "undefined" || diffMethod == null) {
16
+ if (
17
+ typeof diffMethod === "undefined" ||
18
+ diffMethod == null ||
19
+ typeof diffModule === "undefined" ||
20
+ diffModule == null
21
+ ) {
16
22
  return true;
17
23
  }
18
24
 
@@ -37,24 +43,29 @@ const getPrinter = (
37
43
  printerModule,
38
44
  skipDocDirective,
39
45
  ) => {
46
+ let Printer = undefined;
47
+
40
48
  if (typeof printerModule !== "string") {
41
49
  throw new Error(
42
- "Invalid printer module name in printTypeOptions settings.",
50
+ 'Invalid printer module name in "printTypeOptions" settings.',
43
51
  );
44
52
  }
45
53
 
46
54
  try {
47
- const Printer = require(printerModule);
48
- return new Printer(schema, baseURL, linkRoot, {
49
- groups,
50
- printTypeOptions,
51
- skipDocDirective,
52
- });
55
+ Printer = require(printerModule);
53
56
  } catch (error) {
54
57
  throw new Error(
55
- `Cannot find module '${printerModule}' from @graphql-markdown/core in printTypeOptions settings.`,
58
+ `Cannot find module '${printerModule}' for @graphql-markdown/core in "printTypeOptions" settings.`,
56
59
  );
57
60
  }
61
+
62
+ Printer.init(schema, baseURL, linkRoot, {
63
+ groups,
64
+ printTypeOptions,
65
+ skipDocDirective,
66
+ });
67
+
68
+ return Printer;
58
69
  };
59
70
 
60
71
  const generateDocFromSchema = async ({
@@ -73,6 +84,8 @@ const generateDocFromSchema = async ({
73
84
  printer: printerModule,
74
85
  skipDocDirective,
75
86
  }) => {
87
+ const start = process.hrtime.bigint();
88
+
76
89
  const loaders = getDocumentLoaders(loadersList);
77
90
  const schema = await loadSchema(schemaLocation, loaders);
78
91
 
@@ -92,15 +105,10 @@ const generateDocFromSchema = async ({
92
105
  printerModule,
93
106
  skipDocDirective,
94
107
  );
95
- const renderer = new Renderer(
96
- printer,
97
- outputDir,
98
- baseURL,
99
- groups,
100
- prettify,
101
- docOptions,
102
- skipDocDirective,
103
- );
108
+ const renderer = new Renderer(printer, outputDir, baseURL, groups, prettify, {
109
+ ...docOptions,
110
+ deprecated: printTypeOptions.deprecated,
111
+ });
104
112
 
105
113
  const pages = await Promise.all(
106
114
  Object.keys(rootTypes).map((typeName) =>
@@ -112,8 +120,10 @@ const generateDocFromSchema = async ({
112
120
 
113
121
  const sidebarPath = await renderer.renderSidebar();
114
122
 
115
- const [sec, msec] = process.hrtime(time);
116
- const duration = (sec + msec / 1e9).toFixed(3);
123
+ const duration = (
124
+ Number(process.hrtime.bigint() - start) / NS_PER_SEC
125
+ ).toFixed(SEC_DECIMALS);
126
+
117
127
  console.info(
118
128
  `Documentation successfully generated in "${outputDir}" with base URL "${baseURL}".`,
119
129
  );
package/src/group-info.js CHANGED
@@ -1,7 +1,3 @@
1
- const {
2
- array: { convertArrayToObject },
3
- } = require("@graphql-markdown/utils");
4
-
5
1
  const DEFAULT_GROUP = "Miscellaneous";
6
2
  const OPTION_REGEX =
7
3
  /^@(?<directive>\w+)\((?<field>\w+)(?:\|=(?<fallback>\w+))?\)/;
@@ -31,10 +27,6 @@ function getGroups(rootTypes, groupByDirective) {
31
27
  Object.keys(rootTypes).forEach((typeName) => {
32
28
  let rootType = rootTypes[typeName];
33
29
  if (typeof rootType != "undefined" && rootType != null) {
34
- if (Array.isArray(rootType)) {
35
- rootType = convertArrayToObject(rootType);
36
- }
37
-
38
30
  Object.keys(rootType).forEach((type) => {
39
31
  groups[type] = getGroupName(rootType[type], groupByDirective);
40
32
  });
package/src/renderer.js CHANGED
@@ -4,9 +4,9 @@ const {
4
4
  object: { hasProperty },
5
5
  string: { toSlug, startCase },
6
6
  url: { pathUrl },
7
- graphql: { hasDirective },
8
7
  prettier: { prettifyJavascript, prettifyMarkdown },
9
8
  fs: { saveFile, ensureDir, copyFile, readFile, fileExists },
9
+ graphql: { isDeprecated },
10
10
  } = require("@graphql-markdown/utils");
11
11
 
12
12
  const { ASSETS_LOCATION } = require("./config");
@@ -15,27 +15,27 @@ const { schemaSidebar } = require(`${ASSETS_LOCATION}/sidebar.json`);
15
15
  const SIDEBAR = "sidebar-schema.js";
16
16
  const HOMEPAGE_ID = "schema";
17
17
  const CATEGORY_YAML = "_category_.yml";
18
+ const SIDEBAR_POSITION = {
19
+ FIRST: 1,
20
+ LAST: 999,
21
+ };
18
22
 
19
23
  module.exports = class Renderer {
20
- constructor(
21
- printer,
22
- outputDir,
23
- baseURL,
24
- group,
25
- prettify,
26
- docOptions,
27
- skipDocDirective,
28
- ) {
24
+ constructor(printer, outputDir, baseURL, group, prettify, docOptions) {
29
25
  this.group = group;
30
26
  this.outputDir = outputDir;
31
27
  this.baseURL = baseURL;
32
28
  this.printer = printer;
33
29
  this.prettify = prettify;
34
30
  this.options = docOptions;
35
- this.skipDocDirective = skipDocDirective;
36
31
  }
37
32
 
38
- async generateCategoryMetafile(category, dirPath) {
33
+ async generateCategoryMetafile(
34
+ category,
35
+ dirPath,
36
+ sidebarPosition = SIDEBAR_POSITION.FIRST,
37
+ styleClass = undefined,
38
+ ) {
39
39
  const filePath = path.join(dirPath, CATEGORY_YAML);
40
40
 
41
41
  if (await fileExists(filePath)) {
@@ -48,9 +48,41 @@ module.exports = class Renderer {
48
48
  const link =
49
49
  typeof this.options === "undefined" || !this.options.index
50
50
  ? "null"
51
- : `\n type: generated-index\n title: '${label} overview'\n`;
51
+ : `\n type: generated-index\n title: '${label} overview'`;
52
+ const className =
53
+ typeof styleClass === "string" ? `className: ${styleClass}\n` : "";
54
+ await saveFile(
55
+ filePath,
56
+ `label: ${label}\nposition: ${sidebarPosition}\n${className}link: ${link}\n`,
57
+ );
58
+ }
52
59
 
53
- await saveFile(filePath, `label: ${label}\nlink: ${link}\n`);
60
+ async generateCategoryMetafileType(type, name, rootTypeName) {
61
+ let dirPath = this.outputDir;
62
+
63
+ if (
64
+ hasProperty(this.options, "deprecated") &&
65
+ this.options.deprecated === "group" &&
66
+ isDeprecated(type)
67
+ ) {
68
+ dirPath = path.join(dirPath, toSlug("deprecated"));
69
+ await this.generateCategoryMetafile(
70
+ "deprecated",
71
+ dirPath,
72
+ SIDEBAR_POSITION.LAST,
73
+ "deprecated",
74
+ );
75
+ }
76
+
77
+ if (hasProperty(this.group, name)) {
78
+ dirPath = path.join(dirPath, toSlug(this.group[name]));
79
+ await this.generateCategoryMetafile(this.group[name], dirPath);
80
+ }
81
+
82
+ dirPath = path.join(dirPath, toSlug(rootTypeName));
83
+ await this.generateCategoryMetafile(rootTypeName, dirPath);
84
+
85
+ return dirPath;
54
86
  }
55
87
 
56
88
  async renderRootTypes(rootTypeName, type) {
@@ -61,15 +93,11 @@ module.exports = class Renderer {
61
93
  return Promise.all(
62
94
  Object.keys(type)
63
95
  .map(async (name) => {
64
- let dirPath = this.outputDir;
65
-
66
- if (hasProperty(this.group, name)) {
67
- dirPath = path.join(dirPath, toSlug(this.group[name]));
68
- await this.generateCategoryMetafile(this.group[name], dirPath);
69
- }
70
-
71
- dirPath = path.join(dirPath, toSlug(rootTypeName));
72
- await this.generateCategoryMetafile(rootTypeName, dirPath);
96
+ const dirPath = await this.generateCategoryMetafileType(
97
+ type[name],
98
+ name,
99
+ rootTypeName,
100
+ );
73
101
 
74
102
  return this.renderTypeEntities(dirPath, name, type[name]);
75
103
  })
@@ -78,18 +106,20 @@ module.exports = class Renderer {
78
106
  }
79
107
 
80
108
  async renderTypeEntities(dirPath, name, type) {
81
- if (
82
- typeof type === "undefined" ||
83
- type === null ||
84
- hasDirective(type, this.skipDocDirective)
85
- ) {
86
- return undefined;
87
- }
88
-
89
109
  const fileName = toSlug(name);
90
110
  const filePath = path.join(path.normalize(dirPath), `${fileName}.mdx`);
91
111
 
92
- const content = this.printer.printType(fileName, type, this.options);
112
+ let content;
113
+ try {
114
+ content = this.printer.printType(fileName, type, this.options);
115
+ if (typeof content === "undefined") {
116
+ return undefined;
117
+ }
118
+ } catch (error) {
119
+ console.log(`An error occurred while processing "${type}"`);
120
+ return undefined;
121
+ }
122
+
93
123
  await saveFile(
94
124
  filePath,
95
125
  this.prettify ? prettifyMarkdown(content) : content,