release: 1.0.0-rc.3

CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changelog and release notes
 
-## Unreleased
+<!-- ## Unreleased -->
 <!-- here goes all the unreleased changes descriptions -->
+## v1.0.0-rc.3
 ### Features
 - **Breaking Change**: remove legacy array inference - now explicit array syntax (`[Item]`) is required
 - **Breaking Change**: update `graphql-js` peer dependency to `^15.1.0`

website/versioned_docs/version-1.0.0-rc.3/bootstrap.md

@@ -0,0 +1,144 @@
+---
+title: Bootstrapping
+id: version-1.0.0-rc.3-bootstrap
+original_id: bootstrap
+---
+
+After creating our resolvers, type classes, and other business-related code, we need to make our app run. First we have to build the schema, then we can expose it with an HTTP server, WebSockets or even MQTT.
+
+## Create Executable Schema
+
+To create an executable schema from type and resolver definitions, we need to use the `buildSchema` function.
+It takes a configuration object as a parameter and returns a promise of a `GraphQLSchema` object.
+
+In the configuration object we must provide a `resolvers` property, which can be an array of resolver classes:
+
+```typescript
+import { FirstResolver, SecondResolver } from "../app/src/resolvers";
+// ...
+const schema = await buildSchema({
+  resolvers: [FirstResolver, SecondResolver],
+});
+```
+
+Be aware that only operations (queries, mutation, etc.) defined in the resolvers classes (and types directly connected to them) will be emitted in schema.
+
+So if we have defined some object types (that implements an interface type [with disabled auto registering](interfaces.md#registering-in-schema)) but are not directly used in other types definition (like a part of an union, a type of a field or a return type of an operation), we need to provide them manually in `orphanedTypes` options of `buildSchema`:
+
+```typescript
+import { FirstResolver, SecondResolver } from "../app/src/resolvers";
+import { FirstObject } from "../app/src/types";
+// ...
+const schema = await buildSchema({
+  resolvers: [FirstResolver, SecondResolver],
+  // here provide all the types that are missing in schema
+  orphanedTypes: [FirstObject],
+});
+```
+
+In case of defining the resolvers array somewhere else (not inline in the `buildSchema`), we need to use the `as const` syntax to inform the TS compiler and satisfy the `NonEmptyArray<T>` constraints:
+
+```typescript
+// resolvers.ts
+export const resolvers = [FirstResolver, SecondResolver] as const;
+
+// schema.ts
+import { resolvers } from "./resolvers";
+
+const schema = await buildSchema({ resolvers });
+```
+
+However, when there are several resolver classes, manual imports can be cumbersome.
+So we can also provide an array of paths to resolver module files instead, which can include globs:
+
+```typescript
+const schema = await buildSchema({
+  resolvers: [__dirname + "/modules/**/*.resolver.{ts,js}", __dirname + "/resolvers/**/*.{ts,js}"],
+});
+```
+
+> Be aware that in case of providing paths to resolvers files, TypeGraphQL will emit all the operations and types that are imported in the resolvers files or their dependencies.
+
+There are also other options related to advanced features like [authorization](authorization.md) or [validation](validation.md) - you can read about them in docs.
+
+To make `await` work, we need to declare it as an async function. Example of `main.ts` file:
+
+```typescript
+import { buildSchema } from "type-graphql";
+
+async function bootstrap() {
+  const schema = await buildSchema({
+    resolvers: [__dirname + "/**/*.resolver.{ts,js}"],
+  });
+
+  // other initialization code, like creating http server
+}
+
+bootstrap(); // actually run the async function
+```
+
+## Create an HTTP GraphQL endpoint
+
+In most cases, the GraphQL app is served by an HTTP server. After building the schema we can create the GraphQL endpoint with a variety of tools such as [`graphql-yoga`](https://github.com/prisma/graphql-yoga) or [`apollo-server`](https://github.com/apollographql/apollo-server). Here is an example using [`apollo-server`](https://github.com/apollographql/apollo-server):
+
+```typescript
+import { ApolloServer } from "apollo-server";
+
+const PORT = process.env.PORT || 4000;
+
+async function bootstrap() {
+  // ... Building schema here
+
+  // Create the GraphQL server
+  const server = new ApolloServer({
+    schema,
+    playground: true,
+  });
+
+  // Start the server
+  const { url } = await server.listen(PORT);
+  console.log(`Server is running, GraphQL Playground available at ${url}`);
+}
+
+bootstrap();
+```
+
+Remember to install the `apollo-server` package from npm - it's not bundled with TypeGraphQL.
+
+Of course you can use the `express-graphql` middleware, `graphql-yoga` or whatever you want 😉
+
+## Create typeDefs and resolvers map
+
+TypeGraphQL provides a second way to generate the GraphQL schema - the `buildTypeDefsAndResolvers` function.
+
+It accepts the same `BuildSchemaOptions` as the `buildSchema` function but instead of an executable `GraphQLSchema`, it creates a typeDefs and resolversMap pair that you can use e.g. with [`graphql-tools`](https://github.com/apollographql/graphql-tools):
+
+```typescript
+import { makeExecutableSchema } from "graphql-tools";
+
+const { typeDefs, resolvers } = await buildTypeDefsAndResolvers({
+  resolvers: [FirstResolver, SecondResolver],
+});
+
+const schema = makeExecutableSchema({ typeDefs, resolvers });
+```
+
+Or even with other libraries that expect the schema info in that shape, like [`apollo-link-state`](https://github.com/apollographql/apollo-link-state):
+
+```typescript
+import { withClientState } from "apollo-link-state";
+
+const { typeDefs, resolvers } = await buildTypeDefsAndResolvers({
+  resolvers: [FirstResolver, SecondResolver],
+});
+
+const stateLink = withClientState({
+  // ...other options like `cache`
+  typeDefs,
+  resolvers,
+});
+
+// ...the rest of `ApolloClient` initialization code
+```
+
+Be aware that some of the TypeGraphQL features (i.a. [query complexity](complexity.md)) might not work with the `buildTypeDefsAndResolvers` approach because they use some low-level `graphql-js` features.

website/versioned_docs/version-1.0.0-rc.3/browser-usage.md

@@ -0,0 +1,40 @@
+---
+title: Browser usage
+id: version-1.0.0-rc.3-browser-usage
+original_id: browser-usage
+---
+
+## Using classes in a client app
+
+Sometimes we might want to use the classes we've created and annotated with TypeGraphQL decorators, in our client app that works in the browser. For example, reusing the args or input classes with `class-validator` decorators or the object type classes with some helpful custom methods.
+
+Since TypeGraphQL is a Node.js framework, it doesn't work in a browser environment, so we may quickly get an error, e.g. `ERROR in ./node_modules/fs.realpath/index.js` or `utils1_promisify is not a function`, while trying to build our app with Webpack. To correct this, we have to configure Webpack to use the decorator shim instead of the normal module. We simply add this plugin code to our webpack config:
+
+```js
+module.exports = {
+  // ... the rest of the webpack config
+  plugins: [
+    // ... here are any other existing plugins that we already have
+    new webpack.NormalModuleReplacementPlugin(/type-graphql$/, resource => {
+      resource.request = resource.request.replace(/type-graphql/, "type-graphql/dist/browser-shim.js");
+    }),
+  ];
+}
+```
+
+In case of cypress, you can adapt the same webpack config trick just by applying the [cypress-webpack-preprocessor](https://github.com/cypress-io/cypress-webpack-preprocessor) plugin.
+
+However, in some TypeScript projects like the ones using Angular, which AoT compiler requires that a full `*.ts` file is provided instead of just a `*.js` and `*.d.ts` files, to use this shim we have to simply set up our TypeScript configuration in `tsconfig.json` to use this file instead of a normal TypeGraphQL module:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "type-graphql": ["./node_modules/type-graphql/dist/browser-shim.ts"]
+    }
+  }
+}
+```
+
+Thanks to this, our bundle will be much lighter as we don't need to embed the whole TypeGraphQL library code in our app.

website/versioned_docs/version-1.0.0-rc.3/examples.md

@@ -0,0 +1,48 @@
+---
+title: Examples
+sidebar_label: List of examples
+id: version-1.0.0-rc.3-examples
+original_id: examples
+---
+
+On the [GitHub repository](https://github.com/MichalLytek/type-graphql) there are a few simple examples of how to use different TypeGraphQL features and how well they integrate with 3rd party libraries.
+
+All examples have an `examples.gql` file with sample queries/mutations/subscriptions that we can execute.
+
+## Basics
+
+- [Simple usage of fields, basic types and resolvers](https://github.com/MichalLytek/type-graphql/tree/master/examples/simple-usage)
+
+## Advanced
+
+- [Enums and unions](https://github.com/MichalLytek/type-graphql/tree/master/examples/enums-and-unions)
+- [Subscriptions (simple)](https://github.com/MichalLytek/type-graphql/tree/master/examples/simple-subscriptions)
+- [Subscriptions (using Redis)](https://github.com/MichalLytek/type-graphql/tree/master/examples/redis-subscriptions)
+- [Interfaces](https://github.com/MichalLytek/type-graphql/tree/master/examples/interfaces-inheritance)
+- [Extensions (metadata)](https://github.com/MichalLytek/type-graphql/tree/master/examples/extensions)
+
+## Features usage
+
+- [Dependency injection (IoC container)](https://github.com/MichalLytek/type-graphql/tree/master/examples/using-container)
+  - [Scoped containers](https://github.com/MichalLytek/type-graphql/tree/master/examples/using-scoped-container)
+- [Authorization](https://github.com/MichalLytek/type-graphql/tree/master/examples/authorization)
+- [Validation](https://github.com/MichalLytek/type-graphql/tree/master/examples/automatic-validation)
+- [Types inheritance](https://github.com/MichalLytek/type-graphql/tree/master/examples/interfaces-inheritance)
+- [Resolvers inheritance](https://github.com/MichalLytek/type-graphql/tree/master/examples/resolvers-inheritance)
+- [Generic types](https://github.com/MichalLytek/type-graphql/tree/master/examples/generic-types)
+- [Mixin classes](https://github.com/MichalLytek/type-graphql/tree/master/examples/mixin-classes)
+- [Middlewares and Custom Decorators](https://github.com/MichalLytek/type-graphql/tree/master/examples/middlewares-custom-decorators)
+- [Query complexity](https://github.com/MichalLytek/type-graphql/tree/master/examples/query-complexity)
+
+## 3rd party libs integration
+
+- [TypeORM (manual, synchronous) \*](https://github.com/MichalLytek/type-graphql/tree/master/examples/typeorm-basic-usage)
+- [TypeORM (automatic, lazy relations) \*](https://github.com/MichalLytek/type-graphql/tree/master/examples/typeorm-lazy-relations)
+- [Typegoose](https://github.com/MichalLytek/type-graphql/tree/master/examples/typegoose)
+- [Apollo federation](https://github.com/MichalLytek/type-graphql/tree/master/examples/apollo-federation)
+- [Apollo Engine (Apollo Cache Control) \*\*](https://github.com/MichalLytek/type-graphql/tree/master/examples/apollo-engine)
+- [Apollo client state](https://github.com/MichalLytek/type-graphql/tree/master/examples/apollo-client)
+
+_\* Note that we need to edit the TypeORM example's `index.ts` with the credentials of our local database_
+
+_\*\* Note that we need to provide an `APOLLO_ENGINE_API_KEY` env variable with our own API key_