@graphql-markdown/helpers 1.1.3 → 1.2.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/README.md CHANGED
@@ -5,3 +5,58 @@
5
5
  [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=graphql-markdown_helpers&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=graphql-markdown_helpers)
6
6
  [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=graphql-markdown_helpers&metric=coverage)](https://sonarcloud.io/summary/new_code?id=graphql-markdown_helpers)
7
7
  [![Mutation Score](https://img.shields.io/endpoint?label=mutation%20score&style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fgraphql-markdown%2Fgraphql-markdown%2Fmain%3Fmodule%3Dhelpers)](https://dashboard.stryker-mutator.io/reports/github.com/graphql-markdown/graphql-markdown/main?module=helpers)
8
+
9
+ Reusable helpers for customizing GraphQL-Markdown output: rendering custom descriptions and badges from schema directives, wiring directive-based decorators, and shared Markdown-formatting utilities used by formatter presets.
10
+
11
+ ## Installation
12
+
13
+ ```shell
14
+ npm install @graphql-markdown/helpers
15
+ ```
16
+
17
+ ## Usage
18
+
19
+ ### Custom directive description
20
+
21
+ ```js
22
+ import { directiveDescriptor } from "@graphql-markdown/helpers";
23
+
24
+ // customDirective.version.descriptor in your GraphQL-Config
25
+ export default (directive, type) =>
26
+ directiveDescriptor(
27
+ directive,
28
+ type,
29
+ "${description} is ${major}.${minor}.${patch}",
30
+ );
31
+ ```
32
+
33
+ ### Custom directive badge
34
+
35
+ ```js
36
+ import { directiveTag } from "@graphql-markdown/helpers";
37
+
38
+ // customDirective.auth.tag in your GraphQL-Config
39
+ export default (directive, type) =>
40
+ directiveTag(directive, type, "badge--warning");
41
+ ```
42
+
43
+ ### Directive-based decorators
44
+
45
+ ```ts
46
+ import { withDirective } from "@graphql-markdown/helpers";
47
+
48
+ const decorator = withDirective("deprecated", (directive, options, context) => {
49
+ // render decorator content derived from the directive's definition
50
+ });
51
+ ```
52
+
53
+ ## Documentation
54
+
55
+ - [Custom Directives](https://graphql-markdown.dev/docs/advanced/custom-directive)
56
+ - [Decorators](https://graphql-markdown.dev/docs/advanced/decorators)
57
+
58
+ ## License
59
+
60
+ GraphQL-Markdown packages are 100% free and open-source, under the [MIT license](https://github.com/graphql-markdown/graphql-markdown/blob/main/LICENSE).
61
+
62
+ This package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/graphql-markdown/graphql-markdown) to thank us for our work. By contributing to the Treeware forest, you'll be creating employment for local families and restoring wildlife habitats.
@@ -0,0 +1,40 @@
1
+ /**
2
+ * `decorators` render helper for directive-definition-only content.
3
+ *
4
+ * @see [Migrating from `customDirective`](https://graphql-markdown.dev/docs/advanced/decorators#migrating-from-customdirective)
5
+ *
6
+ * @packageDocumentation
7
+ */
8
+ import type { DecoratorContext, DecoratorRenderer, GraphQLDirective, Maybe, PrintTypeOptions } from "@graphql-markdown/types";
9
+ /**
10
+ * Builds a decorator `render` for content derived from a directive's own
11
+ * definition — not per-occurrence argument values, so no `resolve` is
12
+ * needed. Looks the directive up once and skips the decorator (renders
13
+ * nothing) when it is absent from the schema, sparing `render` its own
14
+ * `getDirectiveFromSchema` call and null check.
15
+ *
16
+ * @param name - the schema directive name to resolve.
17
+ * @param render - called with the resolved directive, the print options, and
18
+ * the decorator's context, only when the directive is present in the schema.
19
+ *
20
+ * @returns a {@link DecoratorRenderer} for use as a decorator's `render`.
21
+ *
22
+ * @example
23
+ * ```js
24
+ * import { withDirective } from "@graphql-markdown/helpers/directives/with-directive";
25
+ * import { directiveDescriptor } from "@graphql-markdown/helpers/directives/descriptor";
26
+ * import { hasDirectiveNamed } from "@graphql-markdown/graphql";
27
+ *
28
+ * decorators: {
29
+ * authDescription: {
30
+ * predicate: hasDirectiveNamed("auth"),
31
+ * position: { into: "description" },
32
+ * render: withDirective("auth", (directive, options, { type }) =>
33
+ * directiveDescriptor(directive, type, "Requires the `${requires}` role."),
34
+ * ),
35
+ * },
36
+ * }
37
+ * ```
38
+ */
39
+ export declare const withDirective: (name: string, render: (directive: GraphQLDirective, options: PrintTypeOptions, context: DecoratorContext) => Maybe<string>) => DecoratorRenderer;
40
+ //# sourceMappingURL=with-directive.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"with-directive.d.ts","sourceRoot":"","sources":["../../src/directives/with-directive.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,EACL,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,UACJ,CACN,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,gBAAgB,KACtB,KAAK,CAAC,MAAM,CAAC,KACjB,iBASF,CAAC"}
@@ -0,0 +1,48 @@
1
+ "use strict";
2
+ /**
3
+ * `decorators` render helper for directive-definition-only content.
4
+ *
5
+ * @see [Migrating from `customDirective`](https://graphql-markdown.dev/docs/advanced/decorators#migrating-from-customdirective)
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
10
+ exports.withDirective = void 0;
11
+ const graphql_1 = require("@graphql-markdown/graphql");
12
+ /**
13
+ * Builds a decorator `render` for content derived from a directive's own
14
+ * definition — not per-occurrence argument values, so no `resolve` is
15
+ * needed. Looks the directive up once and skips the decorator (renders
16
+ * nothing) when it is absent from the schema, sparing `render` its own
17
+ * `getDirectiveFromSchema` call and null check.
18
+ *
19
+ * @param name - the schema directive name to resolve.
20
+ * @param render - called with the resolved directive, the print options, and
21
+ * the decorator's context, only when the directive is present in the schema.
22
+ *
23
+ * @returns a {@link DecoratorRenderer} for use as a decorator's `render`.
24
+ *
25
+ * @example
26
+ * ```js
27
+ * import { withDirective } from "@graphql-markdown/helpers/directives/with-directive";
28
+ * import { directiveDescriptor } from "@graphql-markdown/helpers/directives/descriptor";
29
+ * import { hasDirectiveNamed } from "@graphql-markdown/graphql";
30
+ *
31
+ * decorators: {
32
+ * authDescription: {
33
+ * predicate: hasDirectiveNamed("auth"),
34
+ * position: { into: "description" },
35
+ * render: withDirective("auth", (directive, options, { type }) =>
36
+ * directiveDescriptor(directive, type, "Requires the `${requires}` role."),
37
+ * ),
38
+ * },
39
+ * }
40
+ * ```
41
+ */
42
+ const withDirective = (name, render) => {
43
+ return (_values, options, context) => {
44
+ const directive = (0, graphql_1.getDirectiveFromSchema)(name, options);
45
+ return directive ? render(directive, options, context) : undefined;
46
+ };
47
+ };
48
+ exports.withDirective = withDirective;
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from "./directives/descriptor";
2
2
  export * from "./directives/tag";
3
+ export * from "./directives/with-directive";
3
4
  export * from "./formatters/markdown";
4
5
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC"}
package/dist/index.js CHANGED
@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
17
  __exportStar(require("./directives/descriptor"), exports);
18
18
  __exportStar(require("./directives/tag"), exports);
19
+ __exportStar(require("./directives/with-directive"), exports);
19
20
  __exportStar(require("./formatters/markdown"), exports);
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.3",
8
+ "version": "1.2.1",
9
9
  "license": "MIT",
10
10
  "repository": {
11
11
  "type": "git",