From 6f514347597db1653ef2d8fd6032616c9c48267a Mon Sep 17 00:00:00 2001 From: Jason Kuhrt Date: Tue, 8 Dec 2020 13:12:49 -0500 Subject: [PATCH] docs: cover the output type builder api with jsdoc (#715) --- .../030-neuxs-framework-prisma-users.mdx | 2 +- src/definitions/_types.ts | 2 +- src/definitions/definitionBlocks.ts | 308 +++++++++++++++++- src/definitions/extendType.ts | 2 +- src/definitions/objectType.ts | 6 +- 5 files changed, 301 insertions(+), 19 deletions(-) diff --git a/docs/content/040-adoption-guides/030-neuxs-framework-prisma-users.mdx b/docs/content/040-adoption-guides/030-neuxs-framework-prisma-users.mdx index d1224b3a..1d107457 100644 --- a/docs/content/040-adoption-guides/030-neuxs-framework-prisma-users.mdx +++ b/docs/content/040-adoption-guides/030-neuxs-framework-prisma-users.mdx @@ -6,7 +6,7 @@ title: Nexus Framework Prisma Users If you're looking to migrate from the Nexus Framework over to Nexus Schema and you're using the Prisma plugin, this guide is for you. -**This guide assumes you've already followed the [Nexus Framework Users adoption guide](/adoption-guides/nexus-framework-users).** +**This guide assumes you've already followed the [Framework Users adoption Guide](/adoption-guides/nexus-framework-users).** ## Dependencies diff --git a/src/definitions/_types.ts b/src/definitions/_types.ts index c02f5bb6..b488fcbd 100644 --- a/src/definitions/_types.ts +++ b/src/definitions/_types.ts @@ -64,7 +64,7 @@ export interface DeprecationInfo { } /** - * [Nexus Nullability Guide](https://nxs.li/guides/nullability) + * [Nullability Guide](https://nxs.li/guides/nullability) * * Configures the default nullability for fields and arguments. */ diff --git a/src/definitions/definitionBlocks.ts b/src/definitions/definitionBlocks.ts index 4d898d30..29691840 100644 --- a/src/definitions/definitionBlocks.ts +++ b/src/definitions/definitionBlocks.ts @@ -1,9 +1,9 @@ import { GraphQLFieldConfig, GraphQLFieldResolver, GraphQLInputFieldConfig } from 'graphql' +import { messages } from '../messages' import { AllInputTypes, FieldResolver, GetGen, GetGen3, HasGen3, NeedsResolver } from '../typegenTypeHelpers' import { ArgsRecord } from './args' import { AllNexusInputTypeDefs, AllNexusOutputTypeDefs, NexusWrapKind } from './wrapping' import { BaseScalars } from './_types' -import { messages } from '../messages' export interface CommonFieldConfig { /** The description to annotate the GraphQL SDL */ @@ -113,48 +113,330 @@ export interface OutputDefinitionBlock /** The output definition block is passed to the "definition" function property of the "objectType" / "interfaceType" */ export class OutputDefinitionBlock { + /** The name of the enclosing object type. */ readonly typeName: string + constructor(protected typeBuilder: OutputDefinitionBuilder, protected wrapping?: NexusWrapKind[]) { this.typeName = typeBuilder.typeName this.typeBuilder.addDynamicOutputMembers(this, this.wrapping) } + /** + * [API Docs](https://nxs.li/docs/api/list) | [GraphQL 2018 + * Spec](https://spec.graphql.org/June2018/#sec-Type-System.List) + * + * Chain this property to wrap the right-hand-side type (the field type, another list, nonNull, etc.) with a + * List type. + * + * Chains are read backwards, right to left, like function composition. In other words the thing on the left + * wraps the thing on the right. + * + * This is a shorthand equivalent to: + * + * `t.field('...', { type: list('...') })` + * + * @example + * objectType({ + * name: 'User', + * definition(t) { + * t.list.nonNull.string('aliases') + * }, + * }) + * + * // GraphQL SDL + * // ----------- + * // + * // type User { + * // aliases: [String!] + * // } + */ get list() { return this._wrapClass('List') } + /** + * [API Docs](https://nxs.li/docs/api/nonNull) | [Nexus Nullability + * Guide](https://nexusjs.org/docs/guides/nullability) | [GraphQL 2018 + * Spec](https://spec.graphql.org/June2018/#sec-Type-System.Non-Null) + * + * Chain this property to wrap the right-hand-side type (the field type or a list) with a Non-Null type. + * + * In Nexus output types are nullable by default so this is useful to configure a field differently. Note if + * you find yourself using this most of the time then what you probably what is to change the + * nonNullDefaults configuration either gloally in your makeSchema config or at the type definition level + * in one of your type configs to be false for outputs. + * + * Chains are read backwards, right to left, like function composition. In other words the thing on the left + * wraps the thing on the right. + * + * This is a shorthand equivalent to: + * + * `t.field('...', { type: nonNull('...') })` + * + * @example + * objectType({ + * name: 'User', + * definition(t) { + * t.nonNull.list.string('aliases') + * }, + * }) + * + * // GraphQL SDL + * // ----------- + * // + * // type User { + * // aliases: [String]! + * // } + */ get nonNull(): Omit, 'nonNull' | 'nullable'> { return this._wrapClass('NonNull') } + /** + * [API Docs](https://nxs.li/docs/api/null) | [Nexus Nullability + * Guide](https://nexusjs.org/docs/guides/nullability) | [GraphQL 2018 + * Spec](https://spec.graphql.org/June2018/#sec-Type-System.Non-Null) + * + * Chain this property to _unwrap_ the right-hand-side type (the field type or a list) of a Non-Null type. + * + * In Nexus output types are nullable by default so this is only useful when you have changed your + * nonNullDefaults configuration either gloally in your makeSchema config or at the type definition level + * in one of your type configs to be false for outputs. + * + * Chains are read backwards, right to left, like function composition. In other words the thing on the left + * wraps the thing on the right. + * + * This is a shorthand equivalent to: + * + * `t.field('...', { type: nullable('...') })` + * + * @example + * objectType({ + * name: 'User', + * nonNullDefaults: { + * outputs: true, + * }, + * definition(t) { + * t.id('id') + * t.nullable.string('bio') + * }, + * }) + * + * // GraphQL SDL + * // ----------- + * // + * // type User { + * // id: ID! + * // bio: String + * // } + */ get nullable(): Omit, 'nonNull' | 'nullable'> { return this._wrapClass('Null') } - string(fieldName: FieldName, ...opts: ScalarOutSpread) { - this.addScalarField(fieldName, 'String', opts) + /** + * [GraphQL 2018 spec](https://spec.graphql.org/June2018/#sec-Boolean) + * + * Define a field whose type is Boolean. + * + * Boolean types are [scalars](https://spec.graphql.org/June2018/#sec-Scalars) representing true or false. + * They are represented in JavaScript using the [boolean primitive + * type](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean). + * + * This is a shorthand equivalent to: + * + * ` t.field('...', { type: boolean() }) ` + * + * @example + * objectType({ + * name: 'User', + * definition(t) { + * t.boolean('active') + * }, + * }) + * + * @param name The name of this field. Must conform to the regex pattern: [_A-Za-z][_0-9A-Za-z]* + * @param config The configuration for things like the field's type, its description, its arguments, its + * resolver, and more. See jsdoc on each field within for details. + * + * This parameter is optional if no resolver is required. No resolver is required if the [source + * typing](https://nxs.li/guides/backing-types) includes a field whose name matches this one and whose + * type is compatable. The default resolver behaviour will be to simply return that field from the + * received source type. + */ + boolean(name: FieldName, ...config: ScalarOutSpread) { + this.addScalarField(name, 'Boolean', config) } - int(fieldName: FieldName, ...opts: ScalarOutSpread) { - this.addScalarField(fieldName, 'Int', opts) + /** + * [GraphQL 2018 spec](https://spec.graphql.org/June2018/#sec-String) + * + * Define a field whose type is String. + * + * String types are [scalars](https://spec.graphql.org/June2018/#sec-Scalars) representing UTF-8 (aka. + * unicode) character sequences. It is most often used to represent free-form human-readable text. They are + * represented in JavaScript using the [string priimtive + * type](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String). + * + * This is a shorthand, equivalent to: + * + * ` t.field('...', { type: string() }) ` + * + * @example + * objectType({ + * name: 'User', + * definition(t) { + * t.string('bio') + * }, + * }) + * + * @param name The name of this field. Must conform to the regex pattern: [_A-Za-z][_0-9A-Za-z]* + * @param config The configuration for things like the field's type, its description, its arguments, its + * resolver, and more. See jsdoc on each field within for details. + * + * This parameter is optional if no resolver is required. No resolver is required if the [source + * typing](https://nxs.li/guides/backing-types) includes a field whose name matches this one and whose + * type is compatable. The default resolver behaviour will be to simply return that field from the + * received source type. + */ + string(name: FieldName, ...config: ScalarOutSpread) { + this.addScalarField(name, 'String', config) } - boolean(fieldName: FieldName, ...opts: ScalarOutSpread) { - this.addScalarField(fieldName, 'Boolean', opts) + /** + * [GraphQL 2018 spec](https://spec.graphql.org/June2018/#sec-ID) + * + * Define a field whose type is ID. + * + * ID types are [scalars](https://spec.graphql.org/June2018/#sec-Scalars) representing unique identifiers + * often used to refetch an object or as the key for a cache. It is serialized in the same way as the + * [String](https://spec.graphql.org/June2018/#sec-String) type but unlike String not intended to be + * human-readable. They are represented in JavaScript using the [string priimtive + * type](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String). + * + * This is a shorthand, equivalent to: + * + * ` t.field('...', { type: id() }) ` + * + * @example + * objectType({ + * name: 'User', + * definition(t) { + * t.id('id') + * }, + * }) + * + * @param name The name of this field. Must conform to the regex pattern: [_A-Za-z][_0-9A-Za-z]* + * @param config The configuration for things like the field's type, its description, its arguments, its + * resolver, and more. See jsdoc on each field within for details. + * + * This parameter is optional if no resolver is required. No resolver is required if the [source + * typing](https://nxs.li/guides/backing-types) includes a field whose name matches this one and whose + * type is compatable. The default resolver behaviour will be to simply return that field from the + * received source type. + */ + id(name: FieldName, ...config: ScalarOutSpread) { + this.addScalarField(name, 'ID', config) } - id(fieldName: FieldName, ...opts: ScalarOutSpread) { - this.addScalarField(fieldName, 'ID', opts) + /** + * [GraphQL 2018 spec](https://spec.graphql.org/June2018/#sec-Int) + * + * Define a field whose type is Int. + * + * Int types are [scalars](https://spec.graphql.org/June2018/#sec-Scalars) representing a signed 32-bit + * numeric non-fractional value. They are represented in JavaScript using the [number primitive + * type](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number). + * + * This is a shorthand equivalent to: + * + * ` t.field('...', { type: int() }) ` + * + * @example + * objectType({ + * name: 'User', + * definition(t) { + * t.int('age') + * }, + * }) + * + * @param name The name of this field. Must conform to the regex pattern: [_A-Za-z][_0-9A-Za-z]* + * @param config The configuration for things like the field's type, its description, its arguments, its + * resolver, and more. See jsdoc on each field within for details. + * + * This parameter is optional if no resolver is required. No resolver is required if the [source + * typing](https://nxs.li/guides/backing-types) includes a field whose name matches this one and whose + * type is compatable. The default resolver behaviour will be to simply return that field from the + * received source type. + */ + int(name: FieldName, ...config: ScalarOutSpread) { + this.addScalarField(name, 'Int', config) } - float(fieldName: FieldName, ...opts: ScalarOutSpread) { - this.addScalarField(fieldName, 'Float', opts) + /** + * [GraphQL 2018 spec](https://spec.graphql.org/June2018/#sec-Float) + * + * Define a field whose type is Float. + * + * Float types are [scalars](https://spec.graphql.org/June2018/#sec-Scalars) representing signed + * double‐precision fractional values as specified by IEEE 754. They are represented in JavaScript using + * the [number primitive + * type](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number). + * + * This is a shorthand, equivalent to: + * + * ` t.field('...', { type: float() }) ` + * + * @example + * objectType({ + * name: 'User', + * definition(t) { + * t.float('height') + * }, + * }) + * + * @param name The name of this field. Must conform to the regex pattern: [_A-Za-z][_0-9A-Za-z]* + * @param config The configuration for things like the field's type, its description, its arguments, its + * resolver, and more. See jsdoc on each field within for details. + * + * This parameter is optional if no resolver is required. No resolver is required if the [source + * typing](https://nxs.li/guides/backing-types) includes a field whose name matches this one and whose + * type is compatable. The default resolver behaviour will be to simply return that field from the + * received source type. + */ + float(name: FieldName, ...config: ScalarOutSpread) { + this.addScalarField(name, 'Float', config) } - field(name: FieldName, fieldConfig: FieldOutConfig) { + /** + * [GraphQL 2018 Spec](https://spec.graphql.org/June2018/#sec-Language.Fields) + * + * Define a field on this object. + * + * A field describes one discrete piece of information available to request within a [selection + * set](https://spec.graphql.org/June2018/#sec-Selection-Sets). They are in fact most of what any selection + * set will contain. Fields can be typed as scalars (marking the terminal point of a branch of a selection + * set) or as other object types in your schema thus allowing you to model relationships between things. + * + * @example + * objectType({ + * name: 'User', + * definition(t) { + * t.field('id', { + * type: id(), + * description: 'The unique identification number for this user', + * }) + * }, + * }) + * + * @param name The name of this field. Must conform to the regex pattern: [_A-Za-z][_0-9A-Za-z]* + * @param config The configuration for things like the field's type, its description, its arguments, + * its resolver, and more. See jsdoc on each field within for details. + */ + field(name: FieldName, config: FieldOutConfig) { this.typeBuilder.addField({ name, - ...fieldConfig, + ...config, configFor: 'outputField', wrapping: this.wrapping, parentType: this.typeName, diff --git a/src/definitions/extendType.ts b/src/definitions/extendType.ts index 532984f2..93276c3b 100644 --- a/src/definitions/extendType.ts +++ b/src/definitions/extendType.ts @@ -44,7 +44,7 @@ export class NexusExtendTypeDef { withNexusSymbol(NexusExtendTypeDef, NexusTypes.ExtendObject) /** - * [Nexus Docs](https://nxs.li/docs/api/extend-type) + * [API Docs](https://nxs.li/docs/api/extend-type) * * Add new fields to an existing objectType. * diff --git a/src/definitions/objectType.ts b/src/definitions/objectType.ts index 5017c7bf..65ed334d 100644 --- a/src/definitions/objectType.ts +++ b/src/definitions/objectType.ts @@ -52,7 +52,7 @@ export type NexusObjectTypeConfig = { */ name: TypeName /** - * [Nexus Nullability Guide](https://nxs.li/guides/nullability) + * [Nullability Guide](https://nxs.li/guides/nullability) * * Configures the default nullability for fields and arguments in this object. * @@ -104,7 +104,7 @@ export type NexusObjectTypeConfig = { */ description?: string | null /** - * [Nexus Backing Types Guide](https://nxs.li/guides/backing-types) + * [Source Types Guide](https://nxs.li/guides/backing-types) * * Specify the backing type for this object type. * @@ -182,7 +182,7 @@ export class NexusObjectTypeDef { withNexusSymbol(NexusObjectTypeDef, NexusTypes.Object) /** - * [Nexus Docs](https://nxs.li/docs/api/object-type) | [GraphQL.org + * [API Docs](https://nxs.li/docs/api/object-type) | [GraphQL.org * Docs](https://graphql.org/learn/schema/#object-types-and-fields) | [GraphQL 2018 * Spec](https://spec.graphql.org/June2018/#sec-Objects) *