Merge branch 'master' into feat/better-modules-import

Author: Weakky

.gitignore

@@ -53,8 +53,8 @@ yarn-error.log*
 
 .DS_Store
 .vscode
-dist
-tsconfig.tsbuildinfo
+dist*
+*.tsbuildinfo
 
 .now
 

docs/_sidebar.md

@@ -40,6 +40,7 @@
 
 - Meta
 
+- [Roadmap ⤤](https://github.com/orgs/graphql-nexus/projects/1)
 - [Changelog](changelog)
 - [Architecture](architecture)
 

docs/api/modules/main.md

@@ -18,14 +18,12 @@ app.schema.queryType({
     t.field('foo', { type: 'String' })
   },
 })
-
-app.server.start()
 ```
 
 **Example of imporrting named exports**
 
 ```ts
-import { schema, server, settings, log } from 'nexus'
+import { schema, settings, log } from 'nexus'
 
 log.info('hello world')
 
@@ -40,6 +38,4 @@ schema.queryType({
     t.field('foo', { type: 'String' })
   },
 })
-
-server.start()
 ```

docs/api/modules/main/exports/schema.md

@@ -1055,6 +1055,49 @@ schema.queryType({
  */
 ```
 
+### `importType`
+
+##### Signature
+
+```ts
+(scalarType: GraphQLScalarType, methodName?: string): GraphQLScalarType
+(type: GraphQLNamedType): GraphQLNamedType
+```
+
+`schema.importType` is useful for adding existing GraphQL.js types into your Nexus schema.
+
+[Check out this repository](https://github.com/Urigo/graphql-scalars) for a handful list of useful scalar types that might be useful to your GraphQL API.
+
+When passing a `GraphQLScalarType`, you can additionally pass a `methodName` as a second parameter, which will augment the `t` parameter of your definition builder with a convenient method to create a field of the associated type.
+
+##### Example: Adding a date scalar type
+
+```ts
+import { schema } from 'nexus'
+import { GraphQLDate } from 'graphql-iso-date'
+     
+schema.importType(GraphQLDate, 'date')
+     
+schema.objectType({
+  name: 'SomeObject',
+  definition(t) {
+    t.date('createdAt') // t.date() is now available (with types!) thanks to `importType`
+  },
+})
+```
+
+`schema.importType` can also be used to add types from an existing GraphQL schema into your Nexus schema. This is useful to incrementally adopt Nexus if you already have a GraphQL schema built with a different technology than Nexus.
+
+##### Example: Adding types from a schema-first schema
+
+```ts
+import { schema } from 'nexus'
+import { existingSchema } from './existing-schema'
+
+
+Object.values(existingSchema.getTypeMap()).forEach(schema.importType)
+```
+
 ### Type Glossary
 
 #### `I` `FieldConfig`

docs/api/modules/testing.md

@@ -12,21 +12,20 @@ This context can be augmented by plugins.
 function createTestContext(opts?: CreateTestContextOptions): Promise<TestContext>
 ```
 
-
 ##### Example With Jest
 
 ```ts
-import { } from 'nexus/testing'
+import { TestContext, createTestContext } from 'nexus/testing'
 
 let ctx: TestContext
 
 beforeAll(async () => {
-  ctx = await createTestContext()
-  await ctx.server.start()
+  Object.assign(ctx, await createTestContext())
+  await ctx.app.start()
 })
 
 afterAll(async () => {
-  await ctx.server.stop()
+  await ctx.app.stop()
 })
 
 test('hello', async () => {

docs/architecture.md

@@ -6,6 +6,91 @@ todo
 
 todo
 
+## Plugins
+
+### Diagrams
+
+#### Plugin Tree Shaking
+
+![plugin-tree-shaking](https://dsc.cloud/661643/plugin-tree-shaking.png)
+
+### Glossary
+
+#### Entrypoint
+
+A plugin entrypoint is responsible for returning the plugin's manifest input. This is what users actually deal with at the app layer.
+
+```ts
+import { prisma } from 'nexus-plugin-prisma'
+//       ~~~~~~ <------------- The entrypoint, returns a manifest input
+import { use } from 'nexus'
+
+use(prisma())
+```
+
+#### Manifest
+
+A plugin manifest describes logistical information about a plugin like where its package file is located on disk, what versions of Nexus it is compatible with, and more.
+
+Plugin manifests are created by Nexus by processing the manifest inputs returned by plugin entrypoints.
+
+```ts
+import { prisma } from 'nexus-plugin-prisma'
+
+const prismaPluginManifestInput = prisma()
+```
+
+This lazy approach allows Nexus the flexibility it needs to provide features like automatic environment variable plugin settings injection and tree-shaking.
+
+#### Manifest Input
+
+A manifest input is the view of manifests that plugin authors work with. It models the minimum information that Nexus needs to build the plugin manifest. It is also more human friendly, for example minimizing the number of required fields. Developer experience is not the primary motivation here however. We want Nexus to control as much as possible, so the less the human has to specify the more we achieve this goal. For example we ask for a path to package json rather than the contents of it. We want Nexus to be the one that reads it, when and how it wants.
+
+#### Dimension
+
+A plugin dimension represents a high-level area of plugin concern that are separated by module from other dimensions. In other words, each dimension has its own entrypoint. Nexus will directly import it. A dimension is found by Nexus from Nexus reading the Plugin manifest.
+
+There are three dimensions: worktime, testtime, and runtime. Worktime allows plugins to tap into the CLI, the builder, dev mode, and more. Testtime allows plugins to tap into features of the Nexus testing component. Runtime allows plugins to tap into the API.
+
+Directionally Nexus is on a good track, but there is work still left to do. The names are a bit confusing when you dig into the details, and the supposed separation between worktime/runtime has undesirable "loopholes" because of reflection. Details;
+
+1.  Runtime dimension does not mean plugging exclusively into what is run in your production code. There are actually reasons to plug into the runtime for ostensibly worktime beneit... This is due to Nexus' so-called reflection system, wherein the app is run in the background during development for development purposes.
+
+2.  The rationale for splitting worktime from runtime is clear, tree-shaking alone makes the case for it. However the separation between worktime and testing is less clear, perhaps nonsense, and so may be revisited in the future.
+
+3.  We've talked about motivation for separating worktime from runtime, yet there are runtime parts for worktime (reflection). What this means is that expensive dependencies can make there way into the runtime dimension that a user should actually _not_ be paying for in production runtime.
+
+#### Lens
+
+A plugin lens is just a specialized api into a subset of Nexus to hook into, extend, manipulate, and react to it during execution. The name "lens" is arbitrary. The choice comes from it being "view" into Nexus. Each dimension has its own specialized lens.
+
+#### Dimension Entrypoint
+
+Just like the plugin has a top level entrypoint so to does each dimension within the plugin have its own entrypoint. These sub-entrypoints can be thought as sub-plugins, with the top-level plugin just being a grouping mechanism.
+
+### Comparisons to Other Systems
+
+#### Rollup
+
+- Like Rollup plugins are prefixed with `<tool-name>-plugin-<plugin-name>`
+- We have considered but so far not put first-party Nexus plugins under the pattern `@nexus/plugin-<plugin-name>`. Rollup made this transition retroactively.
+- Rollup suggests plugins have a default export so that are much easier to use on the command line. Nexus suggests plugins also have default exports for similar system-usability reasons (not cli in Nexus' case, but other future features maybe like auto-use).
+
+### Loading Flow
+
+todo  
+what follows is a stub
+
+1. capture the used plugins in the app
+1. validate entrypoints
+1. transform entrypoints into manifests
+1. for each dimension (work, test, run) in the manifest
+   1. import it
+   1. catch any import errors
+   1. validate imported value
+   1. load plugin
+   1. catch any load errors
+
 ## Build Flow
 
 1. The app layout is calculated  
@@ -25,27 +110,12 @@ todo
 1. A new TypeScript instance is created so that the types generated in the previous step are picked up by the checker. This should be faster because it reuses the TypeScript cache created in the previous step.
 1. The app is type checked
 1. The app is transpiled
-1. The app is emitted into `node_modules/.build`. This convention keeps derived files in a well known generally ignored location.
+1. The app is emitted into `.nexus/build`. This convention keeps derived files in a well known generally ignored location.
 1. A production-oriented start module is generated differing in the following ways:
    - paths are relative
    - typescript not hooked into module extensions
    - plugins are imported for tree-shaking
 
-## Plugin Loading Flow
-
-todo  
-what follows is a stub
-
-1. capture the used plugins in the app
-1. validate entrypoints
-1. transform entrypoints into manifests
-1. for each dimension (work, test, run) in the manifest
-   1. import it
-   1. catch any import errors
-   1. validate imported value
-   1. load plugin
-   1. catch any load errors
-
 ## Glossary
 
 ### Assembly

docs/community/roadmap.md

@@ -22,10 +22,12 @@
 - Plugins
 
 - [`prisma`](plugins/prisma)
+- [`jwt-auth`](https://github.com/Camji55/nexus-plugin-jwt-auth)
+- [`graphql-shield`](https://github.com/lvauvillier/nexus-plugin-shield)
 
-- API
+* API
 
-- [`nexus`](api/modules/main)
+* [`nexus`](api/modules/main)
 
   - [`schema`](api/modules/main/exports/schema)
   - [`log`](api/modules/main/exports/logger)
@@ -35,11 +37,17 @@
 
 - [`nexus/testing`](api/modules/testing)
 
-* [`nexus/plugin`](api/modules/plugin)
+- [`nexus/plugin`](api/modules/plugin)
 
-- Components Standalone
+- Meta
 
-- [`@nexus/schema`](components/schema/about)
+- [Roadmap ⤤](https://github.com/orgs/graphql-nexus/projects/1)
+- [Changelog](changelog)
+- [Architecture](architecture)
+
+* Components Standalone
+
+* [`@nexus/schema`](components/schema/about)
 
   - [API](components/schema/api/index.md)
     - [objectType](components/schema/api/copy/api-objectType)

docs/components/schema/api/_sidebar.md

@@ -108,7 +108,7 @@ You should only be working with the `nexus` CLI. Below shows the example scripts
 -    "dev": "ts-node-dev --no-notify --respawn --transpileOnly src/server",
 +    "dev": "nexus dev",
 +    "build": "nexus build",
-+    "start": "node node_modules/.build"
++    "start": "node .nexus/build"
   },
 ```
 

docs/getting-started/migrate-from-nexus-schema.md

@@ -1,4 +1,4 @@
-> For this tutorial we will use PostgreSQL as our database. Install PostgreSQL if needed and then get its connection URL. Check out [our postgresql setup guide](references/recipes?id=local-postgresql) if unsure.
+> For this tutorial we will use PostgreSQL as our database. Install PostgreSQL if needed and then get its connection URL. Check out [our postgresql setup guide](references/recipes?id=localql) if unsure.
 
 ## Scaffold Project
 

docs/getting-started/tutorial.md

@@ -21,7 +21,7 @@
 
 - Out Root is the place where the transpiled TypeScript (to JavaScript) modules will be emitted to. The folder structure mimicks that of the source root.
 - Out Root is defined by setting `compilerOptions.outDir`.
-- If you do not specify it then Nexus will default to `node_modules/.build`. Unlike with `rootDir` Nexus will not scaffold the default into your `tsconfig.json` because its presence has no impact upon VSCode.
+- If you do not specify it then Nexus will default to `.nexus/build`. Unlike with `rootDir` Nexus will not scaffold the default into your `tsconfig.json` because its presence has no impact upon VSCode.
 - You can override its value interactively with `nexus build --out`.
 
 ##### Check-Only Builds

docs/guides/project-layout.md

@@ -20,4 +20,4 @@
   }
   ```
 
-- See the [Next.JS example](https://github.com/graphql-nexus/examples/tree/master/integration-nextjs) for a functioning serverless reference.
+- See the [Next.JS example](https://github.com/graphql-nexus/examples/tree/master/with-nextjs) for a functioning serverless reference.

docs/guides/serverless.md

@@ -24,11 +24,11 @@ export function createTestContext(): TestContext {
 
   beforeAll(async () => {
     Object.assign(ctx, await originalCreateTestContext())
-    await ctx.app.server.start()
+    await ctx.app.start()
   })
 
   afterAll(async () => {
-    await ctx.app.server.stop()
+    await ctx.app.stop()
   })
 
   return ctx
@@ -88,7 +88,7 @@ Integration testing with a database can add a lot of complexity to your test sui
 
 Integration between Nexus' test and database systems is young and still missing many features. Below we will cover some utilities and patterns that you can copy into your project meanwhile.
 
-> Note: This assumes you have [setup a PostgreSQL database running locally](references/recipes?id=local-postgresql). You could use any database supported by Prisma though.
+> Note: This assumes you have [setup a PostgreSQL database running locally](references/recipes?id=localql). You could use any database supported by Prisma though.
 
 1. Install new development dependencies for upcoming test utilities.
 

docs/guides/testing.md

@@ -219,7 +219,7 @@ schema.queryType({
   },
 })
 
-schema.schema.mutationType({
+schema.mutationType({
   definition(t) {
     t.crud.createOneUser()
     t.crud.createOnePost()