From 6e395b9f6b9ac66c43c95fc92f6f5bf67b6da70e Mon Sep 17 00:00:00 2001 From: Jason Kuhrt Date: Tue, 9 Mar 2021 15:15:22 -0500 Subject: [PATCH] improve!: better names, auto-import friendly, jsdoc (#12) --- .prettierrc.js | 1 - .vscode/settings.json | 3 + README.md | 16 +++-- package.json | 2 +- src/helpers/prismaExternalToInternalDMMF.ts | 2 +- src/scalars/DateTime.ts | 31 +++++++- src/scalars/Json.ts | 30 +++++++- src/scalars/index.ts | 80 ++++++++++++++++++++- yarn.lock | 43 +++++------ 9 files changed, 171 insertions(+), 37 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.prettierrc.js b/.prettierrc.js index 4096910f8..b7fef9ed6 100644 --- a/.prettierrc.js +++ b/.prettierrc.js @@ -1,4 +1,3 @@ module.exports = { ...require('@prisma-labs/prettier-config'), - jsdocParser: true, } diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..21ea2006a --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "gitdoc.enabled": false +} diff --git a/README.md b/README.md index 703485bc5..f9e3bbf33 100644 --- a/README.md +++ b/README.md @@ -110,10 +110,10 @@ However some of the Prisma scalars do not have a natural standard representation **Prisma Standard Scalar to GraphQL Custom Scalar Mapping** -| Prisma | GraphQL | GraphQL Scalar Implementation | -| ---------- | ---------- | ----------------------------------------------------------------- | -| `Json` | `Json` | [JsonObject](https://github.com/Urigo/graphql-scalars#jsonobject) | -| `DateTime` | `DateTime` | [DateTime](https://github.com/Urigo/graphql-scalars#datetime) | +| Prisma | GraphQL | Nexus `t` Helper | GraphQL Scalar Implementation | +| ---------- | ---------- | ---------------- | ----------------------------------------------------------------- | +| `Json` | `Json` | `json` | [JsonObject](https://github.com/Urigo/graphql-scalars#jsonobject) | +| `DateTime` | `DateTime` | `datetime` | [DateTime](https://github.com/Urigo/graphql-scalars#datetime) | > **Note:** Not all Prisma scalar mappings are implemented yet: `Bytes`, `BigInt`, `Decimal`, `Unsupported` @@ -122,11 +122,11 @@ While you are not required to use the implementations supplied by Nexus Prisma, Here is an example using the Nexus Prisma pre-defined custom scalars: ```ts -import * as customScalars from 'nexus-prisma/scalars' +import NexusPrismaScalars from 'nexus-prisma/scalars' import { makeSchema } from 'nexus' makeSchema({ - types: [customScalars], + types: [NexusPrismaScalars], }) ``` @@ -259,6 +259,10 @@ NO_PEER_DEPENDENCY_CHECK=true|1 PEER_DEPENDENCY_CHECK=false|0 ``` +##### Auto-Import Optimized + +- `nexus-prisma/scalars` offers a default export you can easily auto-import by name: `NexusPrismaScalars`. + ## Notes - Versions of `nexus-prisma` package prior to `0.20` were a completely different version of the API, and had also become deprecated at one point to migrate to `nexus-plugi-prisma` when Nexus Framework was being worked on. All of that is history. diff --git a/package.json b/package.json index 0c263ed94..4779cefec 100644 --- a/package.json +++ b/package.json @@ -34,6 +34,7 @@ "prepublishOnly": "yarn build" }, "devDependencies": { + "@homer0/prettier-plugin-jsdoc": "^3.0.0", "@prisma-labs/prettier-config": "0.1.0", "@prisma/client": "2.18.0", "@prisma/sdk": "^2.18.0", @@ -57,7 +58,6 @@ "nexus": "^1.0.0", "nodemon": "^2.0.7", "prettier": "2.2.1", - "prettier-plugin-jsdoc": "^0.3.13", "prisma": "2.18.0", "strip-ansi": "^6.0.0", "ts-jest": "26.5.3", diff --git a/src/helpers/prismaExternalToInternalDMMF.ts b/src/helpers/prismaExternalToInternalDMMF.ts index dc81d5487..d17aba566 100644 --- a/src/helpers/prismaExternalToInternalDMMF.ts +++ b/src/helpers/prismaExternalToInternalDMMF.ts @@ -14,7 +14,7 @@ export function getCountAggregateOutputName(modelName: string): string { } /** - * Turns type: string into type: string[] for all args in order to support union input types + * Turns type: string into type: string[] for all args in order to support union input types. * * @param document */ diff --git a/src/scalars/DateTime.ts b/src/scalars/DateTime.ts index 64ba79335..f2d647b24 100644 --- a/src/scalars/DateTime.ts +++ b/src/scalars/DateTime.ts @@ -2,4 +2,33 @@ import { GraphQLScalarType } from 'graphql' import { DateTimeResolver } from 'graphql-scalars' import { asNexusMethod } from 'nexus' -export const dateTimeScalar = asNexusMethod(new GraphQLScalarType(DateTimeResolver), 'dateTime') +/** + * A Nexus scalar type definition for date-time string at UTC, such as 2007-12-03T10:15:30Z, compliant with + * the \`date-time\` format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for + * representation of dates and times using the Gregorian calendar. + * + * Contributes a scalar to your GraphQL schema called `Datetime`. + * + * Contributes a `t` `[1]` helper method called `dateTime` + * + * `[1]` A `t` helper method refers to a method on the argument given to a `definition` method. Helper methods + * here typically help you quickly create new fields. + * + * @example + * + * import { makeSchema, objectType } from 'nexus' + * import { DateTime } from 'nexus-prisma/scalars' + * + * SomeObject = objectType({ + * name: 'SomeObject', + * definition(t) { + * t.dateTime('someDateTimeField') + * }, + * }) + * + * makeSchema({ + * types: [DateTime, SomeObject], + * }) + * + */ +export const DateTime = asNexusMethod(new GraphQLScalarType(DateTimeResolver), 'dateTime') diff --git a/src/scalars/Json.ts b/src/scalars/Json.ts index ce8247d7e..212763b63 100644 --- a/src/scalars/Json.ts +++ b/src/scalars/Json.ts @@ -2,7 +2,35 @@ import { GraphQLScalarType } from 'graphql' import { JSONObjectResolver } from 'graphql-scalars' import { asNexusMethod } from 'nexus' -export const jsonScalar = asNexusMethod( +/** + * A Nexus scalar type definition for the `JSONObject` scalar type represents JSON objects as specified by + * [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf). + * + * Contributes a scalar to your GraphQL schema called `Json`. + * + * Contributes a `t` `[1]` helper method called `json` + * + * `[1]` A `t` helper method refers to a method on the argument given to a `definition` method. Helper methods + * here typically help you quickly create new fields. + * + * @example + * + * import { makeSchema, objectType } from 'nexus' + * import { Json } from 'nexus-prisma/scalars' + * + * SomeObject = objectType({ + * name: 'SomeObject', + * definition(t) { + * t.json('someJsonField') + * }, + * }) + * + * makeSchema({ + * types: [Json, SomeObject], + * }) + * + */ +export const Json = asNexusMethod( new GraphQLScalarType({ ...JSONObjectResolver, // Override the default 'JsonObject' name with one that matches what Nexus Prisma expects. diff --git a/src/scalars/index.ts b/src/scalars/index.ts index 82e8053db..6989ecd89 100644 --- a/src/scalars/index.ts +++ b/src/scalars/index.ts @@ -1,2 +1,78 @@ -export * from './DateTime' -export * from './Json' +import { DateTime } from './DateTime' +import { Json } from './Json' + +/** + * Predefined Nexus scalar type definitions to satisfy all custom scalars needed in GraphQL to map to the + * native scalars in Prisma. The mapping is as follows: + * + * | Prisma | GraphQL | Nexus `t` Helper | GraphQL Scalar Implementation | + * | ---------- | ---------- | ---- | ----------------------------------------------------------------- | + * | `Json` | `Json` | `json` | [JsonObject](https://github.com/Urigo/graphql-scalars#jsonobject) | + * | `DateTime` | `DateTime` | `datetime` | [DateTime](https://github.com/Urigo/graphql-scalars#datetime) |. + * + * @example + * + * // Use this defualt export + * + * import { makeSchema, objectType } from 'nexus' + * import NexusPrismaScalars from 'nexus-prisma/scalars' + * + * makeSchema({ + * types: [NexusPrismaScalars], + * }) + * + * @example + * + * // Use ESM namespace import if you prefer + * + * import { makeSchema, objectType } from 'nexus' + * import * as NexusPrismaScalars from 'nexus-prisma/scalars' + * + * makeSchema({ + * types: [NexusPrismaScalars], + * }) + * + * @example + * + * // Use only select precefined custom scalars + * + * import { makeSchema, objectType } from 'nexus' + * import { Json } from 'nexus-prisma/scalars' + * + * makeSchema({ + * types: [Json], + * }) + * + * @example + * + * // Use your own custom scalars instead of these. + * + * import { GraphQLScalarType } from 'graphql' + * import { JSONObjectResolver, DateTimeResolver } from 'graphql-scalars' + * import { asNexusMethod, makeSchema } from 'nexus' + * + * const jsonScalar = new GraphQLScalarType({ + * ...JSONObjectResolver, + * // Override the default 'JsonObject' name with one that matches what Nexus Prisma expects. + * name: 'Json', + * }) + * + * const dateTimeScalar = new GraphQLScalarType(DateTimeResolver) + * + * makeSchema({ + * types: [asNexusMethod(jsonScalar, 'json'), asNexusMethod(dateTimeScalar, 'dateTime')], + * }) + * + * @remarks Some Of the Prisma scalars do not have a natural standard representation in GraphQL. For these + * cases Nexus Prisma generates code that references type names matching those scalar names + * in Prisma. Then, you are expected to define those custom scalar types in your GraphQL + * API. For convenience you can use these ones. + */ +const NexusPrismaScalars = { + DateTime, + Json, +} + +export default NexusPrismaScalars + +export { DateTime, Json } diff --git a/yarn.lock b/yarn.lock index 63a483085..73d75c7b2 100644 --- a/yarn.lock +++ b/yarn.lock @@ -321,6 +321,15 @@ minimatch "^3.0.4" strip-json-comments "^3.1.1" +"@homer0/prettier-plugin-jsdoc@^3.0.0": + version "3.0.0" + resolved "https://registry.yarnpkg.com/@homer0/prettier-plugin-jsdoc/-/prettier-plugin-jsdoc-3.0.0.tgz#b4d1989fc86e3e30190e4933a2309def87e53f33" + integrity sha512-JTVA1Wp1T0aHJSqnJAPsctlX09M7U8EX3W05hrdY6Ckz+DHB8D3/vVv2mT7yK9NVwd9De/Jwd5eegV47BtuzyA== + dependencies: + comment-parser "1.1.1" + prettier "^2.2.1" + ramda "0.27.1" + "@istanbuljs/load-nyc-config@^1.0.0": version "1.1.0" resolved "https://registry.yarnpkg.com/@istanbuljs/load-nyc-config/-/load-nyc-config-1.1.0.tgz#fd3db1d59ecf7cf121e80650bb86712f9b55eced" @@ -1485,11 +1494,6 @@ binary-extensions@^2.0.0: resolved "https://registry.yarnpkg.com/binary-extensions/-/binary-extensions-2.2.0.tgz#75f502eeaf9ffde42fc98829645be4ea76bd9e2d" integrity sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA== -binary-search-bounds@^2.0.5: - version "2.0.5" - resolved "https://registry.yarnpkg.com/binary-search-bounds/-/binary-search-bounds-2.0.5.tgz#125e5bd399882f71e6660d4bf1186384e989fba7" - integrity sha512-H0ea4Fd3lS1+sTEB2TgcLoK21lLhwEJzlQv3IN47pJS976Gx4zoWe0ak3q+uYh60ppQxg9F16Ri4tS1sfD4+jA== - bl@^4.0.3: version "4.1.0" resolved "https://registry.yarnpkg.com/bl/-/bl-4.1.0.tgz#451535264182bec2fbbc83a62ab98cf11d9f7b3a" @@ -1845,10 +1849,10 @@ commander@^2.19.0: resolved "https://registry.yarnpkg.com/commander/-/commander-2.20.3.tgz#fd485e84c03eb4881c20722ba48035e8531aeb33" integrity sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ== -comment-parser@^1.1.2: - version "1.1.2" - resolved "https://registry.yarnpkg.com/comment-parser/-/comment-parser-1.1.2.tgz#e5317d7a2ec22b470dcb54a29b25426c30bf39d8" - integrity sha512-AOdq0i8ghZudnYv8RUnHrhTgafUGs61Rdz9jemU5x2lnZwAWyOq7vySo626K59e1fVKH1xSRorJwPVRLSWOoAQ== +comment-parser@1.1.1: + version "1.1.1" + resolved "https://registry.yarnpkg.com/comment-parser/-/comment-parser-1.1.1.tgz#c0581d520677e2cfab1a568e94ea0400df9fe4bd" + integrity sha512-vue7cRi1ZO5/72FJ+wZ5+siTSBlUv3ZksTk8bWD2IkaA6obitzMZP3yI65azTJLckwmi8lxfPP5Sd9oGuZ8e2g== common-tags@^1.8.0: version "1.8.0" @@ -4013,11 +4017,6 @@ lines-and-columns@^1.1.6: resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.1.6.tgz#1c00c743b433cd0a4e80758f7b64a57440d9ff00" integrity sha1-HADHQ7QzzQpOgHWPe2SldEDZ/wA= -linguist-languages@^7.12.2: - version "7.13.0" - resolved "https://registry.yarnpkg.com/linguist-languages/-/linguist-languages-7.13.0.tgz#9f533f3753861755c7414d57211e0df48bf6c113" - integrity sha512-n1X6l+YYbEDtXE9tDr8nYZAgeuKw+qBFvYGzIGltw3Z3oJwS+4vyVtFG5UFa71kvmPWMS3RT/yB95RWzD7MrVQ== - locate-path@^3.0.0: version "3.0.0" resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-3.0.0.tgz#dbec3b3ab759758071b58fe59fc41871af21400e" @@ -4726,16 +4725,7 @@ prepend-http@^2.0.0: resolved "https://registry.yarnpkg.com/prepend-http/-/prepend-http-2.0.0.tgz#e92434bfa5ea8c19f41cdfd401d741a3c819d897" integrity sha1-6SQ0v6XqjBn0HN/UAddBo8gZ2Jc= -prettier-plugin-jsdoc@^0.3.13: - version "0.3.13" - resolved "https://registry.yarnpkg.com/prettier-plugin-jsdoc/-/prettier-plugin-jsdoc-0.3.13.tgz#02894b1b5acbf8a06b930d8e57d39a81eb047afc" - integrity sha512-muq5DMqpMMogRJIiA1eeyVFkjG8H9dU7miXIGQP4qXQgC2IS36wL+Y5WCHN92rowP8DHlQj6dR1eoA8SztnogA== - dependencies: - binary-search-bounds "^2.0.5" - comment-parser "^1.1.2" - linguist-languages "^7.12.2" - -prettier@2.2.1: +prettier@2.2.1, prettier@^2.2.1: version "2.2.1" resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.2.1.tgz#795a1a78dd52f073da0cd42b21f9c91381923ff5" integrity sha512-PqyhM2yCjg/oKkFPtTGUojv7gnZAoG80ttl45O6x2Ug/rMJw4wcc9k6aaf2hibP7BGVCCM33gZoGjyvt9mm16Q== @@ -4830,6 +4820,11 @@ queue-microtask@^1.2.2: resolved "https://registry.yarnpkg.com/queue-microtask/-/queue-microtask-1.2.2.tgz#abf64491e6ecf0f38a6502403d4cda04f372dfd3" integrity sha512-dB15eXv3p2jDlbOiNLyMabYg1/sXvppd8DP2J3EOCQ0AkuSXCW2tP7mnVouVLJKgUMY6yP0kcQDVpLCN13h4Xg== +ramda@0.27.1: + version "0.27.1" + resolved "https://registry.yarnpkg.com/ramda/-/ramda-0.27.1.tgz#66fc2df3ef873874ffc2da6aa8984658abacf5c9" + integrity sha512-PgIdVpn5y5Yns8vqb8FzBUEYn98V3xcPgawAkkgj0YJ0qDsnHCiNmZYfOGMgOvoB0eWFLpYbhxUR3mxfDIMvpw== + rc@^1.2.8: version "1.2.8" resolved "https://registry.yarnpkg.com/rc/-/rc-1.2.8.tgz#cd924bf5200a075b83c188cd6b9e211b7fc0d3ed"