@graphql-markdown/helpers 1.0.0-next.0 → 1.0.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.
@@ -1,2 +1,77 @@
1
+ /**
2
+ * Custom directive `descriptor` helper.
3
+ *
4
+ * @see {@link https://graphql-markdown.github.io/docs/advanced/custom-directive#descriptor | Option `customDirective.[directive].descriptor`}
5
+ *
6
+ * @packageDocumentation
7
+ */
1
8
  import type { GraphQLDirective } from "@graphql-markdown/types";
9
+ /**
10
+ * Helper for rendering custom description from schema directive on type.
11
+ * This is an example on how to build a custom `descriptor` callback.
12
+ *
13
+ * @param directive - the schema directive to parse.
14
+ * @param type - the schema type to be processed for generating a custom description.
15
+ * @param descriptionTemplate - optional template literal-like string for rendering the description (see {@link interpolate}), if not present then the directive description will be used.
16
+ *
17
+ * @returns a custom description based on directive value.
18
+ *
19
+ * @example
20
+ * ```js
21
+ * import { GraphQLDirective, GraphQLScalarType } from "graphql";
22
+ * import { directiveDescriptor } from "@graphql-markdown/helpers/directives/descriptor";
23
+ *
24
+ * const directive = new GraphQLDirective({
25
+ * name: "version",
26
+ * description: "Min version",
27
+ * locations: [],
28
+ * args: {
29
+ * major: { type: GraphQLInt, defaultValue: 0 },
30
+ * minor: { type: GraphQLInt, defaultValue: 0 },
31
+ * patch: { type: GraphQLInt, defaultValue: 0 },
32
+ * },
33
+ * });
34
+ *
35
+ * const type = new GraphQLScalarType<string>({
36
+ * name: "FooBar",
37
+ * astNode: {
38
+ * kind: Kind.SCALAR_TYPE_DEFINITION,
39
+ * name: { kind: Kind.NAME, value: "FooBar" },
40
+ * directives: [
41
+ * {
42
+ * kind: Kind.DIRECTIVE,
43
+ * name: { kind: Kind.NAME, value: "version" },
44
+ * arguments: [
45
+ * {
46
+ * kind: Kind.ARGUMENT,
47
+ * name: { kind: Kind.NAME, value: "major" },
48
+ * value: { kind: Kind.INT, value: "2" },
49
+ * },
50
+ * {
51
+ * kind: Kind.ARGUMENT,
52
+ * name: { kind: Kind.NAME, value: "minor" },
53
+ * value: { kind: Kind.INT, value: "1" },
54
+ * },
55
+ * {
56
+ * kind: Kind.ARGUMENT,
57
+ * name: { kind: Kind.NAME, value: "patch" },
58
+ * value: { kind: Kind.INT, value: "3" },
59
+ * },
60
+ * ],
61
+ * },
62
+ * ],
63
+ * },
64
+ * });
65
+ *
66
+ * directiveDescriptor(directive, type, "${description} is ${major}.${minor}.${patch}");
67
+ * // Expected result: "Min version is 2.1.3"
68
+ *
69
+ * directiveDescriptor(directive, type);
70
+ * // Expected result: "Min version"
71
+ *
72
+ * directiveDescriptor(directive, type, "Version should be at least ^${major}.${minor}.${patch}");
73
+ * // Expected result: "Version should be at least ^2.1.3"
74
+ * ```
75
+ *
76
+ */
2
77
  export declare function directiveDescriptor(directive: GraphQLDirective, type?: unknown, descriptionTemplate?: string): string;
@@ -1,13 +1,90 @@
1
1
  "use strict";
2
+ /**
3
+ * Custom directive `descriptor` helper.
4
+ *
5
+ * @see {@link https://graphql-markdown.github.io/docs/advanced/custom-directive#descriptor | Option `customDirective.[directive].descriptor`}
6
+ *
7
+ * @packageDocumentation
8
+ */
2
9
  Object.defineProperty(exports, "__esModule", { value: true });
3
10
  exports.directiveDescriptor = void 0;
4
11
  const graphql_1 = require("@graphql-markdown/graphql");
5
12
  const interpolate_1 = require("../utils/interpolate");
13
+ /**
14
+ * Helper for rendering custom description from schema directive on type.
15
+ * This is an example on how to build a custom `descriptor` callback.
16
+ *
17
+ * @param directive - the schema directive to parse.
18
+ * @param type - the schema type to be processed for generating a custom description.
19
+ * @param descriptionTemplate - optional template literal-like string for rendering the description (see {@link interpolate}), if not present then the directive description will be used.
20
+ *
21
+ * @returns a custom description based on directive value.
22
+ *
23
+ * @example
24
+ * ```js
25
+ * import { GraphQLDirective, GraphQLScalarType } from "graphql";
26
+ * import { directiveDescriptor } from "@graphql-markdown/helpers/directives/descriptor";
27
+ *
28
+ * const directive = new GraphQLDirective({
29
+ * name: "version",
30
+ * description: "Min version",
31
+ * locations: [],
32
+ * args: {
33
+ * major: { type: GraphQLInt, defaultValue: 0 },
34
+ * minor: { type: GraphQLInt, defaultValue: 0 },
35
+ * patch: { type: GraphQLInt, defaultValue: 0 },
36
+ * },
37
+ * });
38
+ *
39
+ * const type = new GraphQLScalarType<string>({
40
+ * name: "FooBar",
41
+ * astNode: {
42
+ * kind: Kind.SCALAR_TYPE_DEFINITION,
43
+ * name: { kind: Kind.NAME, value: "FooBar" },
44
+ * directives: [
45
+ * {
46
+ * kind: Kind.DIRECTIVE,
47
+ * name: { kind: Kind.NAME, value: "version" },
48
+ * arguments: [
49
+ * {
50
+ * kind: Kind.ARGUMENT,
51
+ * name: { kind: Kind.NAME, value: "major" },
52
+ * value: { kind: Kind.INT, value: "2" },
53
+ * },
54
+ * {
55
+ * kind: Kind.ARGUMENT,
56
+ * name: { kind: Kind.NAME, value: "minor" },
57
+ * value: { kind: Kind.INT, value: "1" },
58
+ * },
59
+ * {
60
+ * kind: Kind.ARGUMENT,
61
+ * name: { kind: Kind.NAME, value: "patch" },
62
+ * value: { kind: Kind.INT, value: "3" },
63
+ * },
64
+ * ],
65
+ * },
66
+ * ],
67
+ * },
68
+ * });
69
+ *
70
+ * directiveDescriptor(directive, type, "${description} is ${major}.${minor}.${patch}");
71
+ * // Expected result: "Min version is 2.1.3"
72
+ *
73
+ * directiveDescriptor(directive, type);
74
+ * // Expected result: "Min version"
75
+ *
76
+ * directiveDescriptor(directive, type, "Version should be at least ^${major}.${minor}.${patch}");
77
+ * // Expected result: "Version should be at least ^2.1.3"
78
+ * ```
79
+ *
80
+ */
6
81
  function directiveDescriptor(directive, type, descriptionTemplate) {
7
82
  const values = (0, graphql_1.getTypeDirectiveValues)(directive, type);
83
+ const description = directive.description ?? "";
84
+ const params = { description, ...values };
8
85
  if (typeof descriptionTemplate !== "string") {
9
- return (0, interpolate_1.interpolate)(directive.description ?? "", values);
86
+ return (0, interpolate_1.interpolate)(description, params);
10
87
  }
11
- return (0, interpolate_1.interpolate)(descriptionTemplate, values);
88
+ return (0, interpolate_1.interpolate)(descriptionTemplate, params);
12
89
  }
13
90
  exports.directiveDescriptor = directiveDescriptor;
@@ -1,2 +1,49 @@
1
+ /**
2
+ * Custom directive `tag` helper.
3
+ *
4
+ * @see {@link https://graphql-markdown.github.io/docs/advanced/custom-directive#tag | Option `customDirective.[directive].tag`}
5
+ *
6
+ * @packageDocumentation
7
+ */
1
8
  import type { Badge, GraphQLDirective } from "@graphql-markdown/types";
9
+ /**
10
+ * Helper for rendering custom description from schema directive on type.
11
+ * This is an example on how to build a custom `tag` callback.
12
+ *
13
+ * @param directive - the schema directive to parse.
14
+ * @param type - the type being processed.
15
+ * @param classname - optional CSS classname, `"badge--secondary"` by default.
16
+ *
17
+ * @returns a custom description based on directive value.
18
+ *
19
+ * @example
20
+ * ```js
21
+ * import { GraphQLDirective, GraphQLScalarType } from "graphql";
22
+ * import { directiveTag } from "@graphql-markdown/helpers/directives/tag";
23
+ *
24
+ * const directive = new GraphQLDirective({
25
+ * name: "auth",
26
+ * description: "Authentication required",
27
+ * locations: [],
28
+ * });
29
+ *
30
+ * const type = new GraphQLScalarType<string>({
31
+ * name: "FooBar",
32
+ * astNode: {
33
+ * kind: Kind.SCALAR_TYPE_DEFINITION,
34
+ * name: { kind: Kind.NAME, value: "FooBar" },
35
+ * directives: [
36
+ * {
37
+ * kind: Kind.DIRECTIVE,
38
+ * name: { kind: Kind.NAME, value: "auth" },
39
+ * },
40
+ * ],
41
+ * },
42
+ * });
43
+ *
44
+ * directiveTag(directive, type);
45
+ * // Expected result: { text: "@auth", classname: "badge--secondary" }
46
+ * ```
47
+ *
48
+ */
2
49
  export declare function directiveTag(directive: GraphQLDirective, type?: unknown, classname?: string): Badge;
@@ -1,6 +1,53 @@
1
1
  "use strict";
2
+ /**
3
+ * Custom directive `tag` helper.
4
+ *
5
+ * @see {@link https://graphql-markdown.github.io/docs/advanced/custom-directive#tag | Option `customDirective.[directive].tag`}
6
+ *
7
+ * @packageDocumentation
8
+ */
2
9
  Object.defineProperty(exports, "__esModule", { value: true });
3
10
  exports.directiveTag = void 0;
11
+ /**
12
+ * Helper for rendering custom description from schema directive on type.
13
+ * This is an example on how to build a custom `tag` callback.
14
+ *
15
+ * @param directive - the schema directive to parse.
16
+ * @param type - the type being processed.
17
+ * @param classname - optional CSS classname, `"badge--secondary"` by default.
18
+ *
19
+ * @returns a custom description based on directive value.
20
+ *
21
+ * @example
22
+ * ```js
23
+ * import { GraphQLDirective, GraphQLScalarType } from "graphql";
24
+ * import { directiveTag } from "@graphql-markdown/helpers/directives/tag";
25
+ *
26
+ * const directive = new GraphQLDirective({
27
+ * name: "auth",
28
+ * description: "Authentication required",
29
+ * locations: [],
30
+ * });
31
+ *
32
+ * const type = new GraphQLScalarType<string>({
33
+ * name: "FooBar",
34
+ * astNode: {
35
+ * kind: Kind.SCALAR_TYPE_DEFINITION,
36
+ * name: { kind: Kind.NAME, value: "FooBar" },
37
+ * directives: [
38
+ * {
39
+ * kind: Kind.DIRECTIVE,
40
+ * name: { kind: Kind.NAME, value: "auth" },
41
+ * },
42
+ * ],
43
+ * },
44
+ * });
45
+ *
46
+ * directiveTag(directive, type);
47
+ * // Expected result: { text: "@auth", classname: "badge--secondary" }
48
+ * ```
49
+ *
50
+ */
4
51
  function directiveTag(directive, type, classname = "badge--secondary") {
5
52
  return {
6
53
  text: `@${directive.name}`,
@@ -1,3 +1,8 @@
1
+ /**
2
+ * Helpers utility functions library.
3
+ *
4
+ * @packageDocumentation
5
+ */
1
6
  import type { Maybe } from "@graphql-markdown/types";
2
7
  /**
3
8
  * Returns the value of the specified property or nested property of an object using a string path.
@@ -8,6 +13,8 @@ import type { Maybe } from "@graphql-markdown/types";
8
13
  * @param obj - the key/value record object.
9
14
  * @param fallback - optional fallback value to be returned if the path cannot be resolved.
10
15
  *
16
+ * @returns the property value if the path is resolved, else returns the `fallback` value.
17
+ *
11
18
  * @example
12
19
  * ```js
13
20
  * import { getObjPath } from '@graphql-markdown/utils/object';
@@ -17,14 +24,26 @@ import type { Maybe } from "@graphql-markdown/types";
17
24
  * getObjPath("foo.bak", { foo: { bar: 42 } }, "fallback"); // Returns "fallback"
18
25
  * ```
19
26
  *
20
- * @returns the property value if the path is resolved, else returns the `fallback` value.
21
- *
22
27
  */
23
28
  export declare function getObjPath(path: Maybe<string>, obj: unknown, fallback?: unknown): unknown;
24
29
  /**
25
- * interpolate
30
+ * Interpolate a template literal-like string.
26
31
  *
27
- * @internal
32
+ * @param template - a string template literal-like.
33
+ * @param variables - a record map of values with variable's name as key and `description` as directive's description.
34
+ * @param fallback - optional fallback value if a variable cannot be substituted.
35
+ *
36
+ * @returns an interpolated new string from the template.
37
+ *
38
+ * @example
39
+ * ```js
40
+ * const values = { foo: 42, bar: { value: "test" } };
41
+ * const template = "${foo} is not ${bar.notfound}";
42
+ *
43
+ * interpolate(template, values, "fallback"); // Expected result: "42 is not fallback",
44
+ * ```
28
45
  *
29
46
  */
30
- export declare function interpolate(template: string, variables: Maybe<Record<string, unknown>>, fallback?: string): string;
47
+ export declare function interpolate(template: string, variables: Maybe<Record<string, unknown> & {
48
+ description?: string;
49
+ }>, fallback?: string): string;
@@ -1,4 +1,9 @@
1
1
  "use strict";
2
+ /**
3
+ * Helpers utility functions library.
4
+ *
5
+ * @packageDocumentation
6
+ */
2
7
  Object.defineProperty(exports, "__esModule", { value: true });
3
8
  exports.interpolate = exports.getObjPath = void 0;
4
9
  const utils_1 = require("@graphql-markdown/utils");
@@ -11,6 +16,8 @@ const utils_1 = require("@graphql-markdown/utils");
11
16
  * @param obj - the key/value record object.
12
17
  * @param fallback - optional fallback value to be returned if the path cannot be resolved.
13
18
  *
19
+ * @returns the property value if the path is resolved, else returns the `fallback` value.
20
+ *
14
21
  * @example
15
22
  * ```js
16
23
  * import { getObjPath } from '@graphql-markdown/utils/object';
@@ -20,22 +27,32 @@ const utils_1 = require("@graphql-markdown/utils");
20
27
  * getObjPath("foo.bak", { foo: { bar: 42 } }, "fallback"); // Returns "fallback"
21
28
  * ```
22
29
  *
23
- * @returns the property value if the path is resolved, else returns the `fallback` value.
24
- *
25
30
  */
26
31
  function getObjPath(path, obj, fallback = "") {
27
32
  if ((0, utils_1.isEmpty)(obj) || typeof path !== "string") {
28
33
  return fallback;
29
34
  }
30
- return path
31
- .split(".")
32
- .reduce((res, key) => res[key] ?? fallback, obj); // eslint-disable-line @typescript-eslint/no-explicit-any
35
+ return path.split(".").reduce((res, key) => {
36
+ return res[key] ?? fallback;
37
+ }, obj); // eslint-disable-line @typescript-eslint/no-explicit-any
33
38
  }
34
39
  exports.getObjPath = getObjPath;
35
40
  /**
36
- * interpolate
41
+ * Interpolate a template literal-like string.
37
42
  *
38
- * @internal
43
+ * @param template - a string template literal-like.
44
+ * @param variables - a record map of values with variable's name as key and `description` as directive's description.
45
+ * @param fallback - optional fallback value if a variable cannot be substituted.
46
+ *
47
+ * @returns an interpolated new string from the template.
48
+ *
49
+ * @example
50
+ * ```js
51
+ * const values = { foo: 42, bar: { value: "test" } };
52
+ * const template = "${foo} is not ${bar.notfound}";
53
+ *
54
+ * interpolate(template, values, "fallback"); // Expected result: "42 is not fallback",
55
+ * ```
39
56
  *
40
57
  */
41
58
  function interpolate(template, variables, fallback) {
package/package.json CHANGED
@@ -5,11 +5,11 @@
5
5
  "bugs": {
6
6
  "url": "https://github.com/graphql-markdown/graphql-markdown/issues"
7
7
  },
8
- "version": "1.0.0-next.0",
8
+ "version": "1.0.1",
9
9
  "license": "MIT",
10
10
  "repository": {
11
11
  "type": "git",
12
- "url": "graphql-markdown/graphql-markdown",
12
+ "url": "git+https://github.com/graphql-markdown/graphql-markdown.git",
13
13
  "directory": "packages/helpers"
14
14
  },
15
15
  "author": {
@@ -56,10 +56,10 @@
56
56
  "docs": "typedoc"
57
57
  },
58
58
  "dependencies": {
59
- "@graphql-markdown/graphql": "^1.0.0-next.0"
59
+ "@graphql-markdown/graphql": "^1.0.1"
60
60
  },
61
61
  "devDependencies": {
62
- "@graphql-markdown/types": "^1.0.0-next.0"
62
+ "@graphql-markdown/types": "^1.0.0"
63
63
  },
64
64
  "directories": {
65
65
  "test": "tests"