Rename root val to source

.changeset/cuddly-wolves-sort.md

@@ -0,0 +1,6 @@
+---
+"@graphql-ts/extend": minor
+"@graphql-ts/schema": minor
+---
+
+Type parameters named `RootVal` have been renamed to `Source` and properties named `__rootVal` have been renamed to `__source`. This won't require code changes unless you've relied on the `__rootVal` properties(which you shouldn't).

package.json

@@ -29,7 +29,7 @@
     "typescript": "^4.3.5"
   },
   "scripts": {
-    "postinstall": "preconstruct dev && manypkg check",
+    "postinstall": "preconstruct dev",
     "release": "preconstruct build && changeset publish",
     "version": "changeset version && pnpm i --frozen-lockfile=false",
     "test": "jest",

packages/extend/package.json

@@ -11,7 +11,7 @@
     "@babel/runtime": "^7.9.2"
   },
   "peerDependencies": {
-    "@graphql-ts/schema": "^0.4.0",
+    "@graphql-ts/schema": "^0.5.0",
     "graphql": "^15.0.0"
   },
   "devDependencies": {

packages/extend/src/index.ts

@@ -67,8 +67,29 @@ const builtinScalars = new Set(specifiedScalarTypes.map((x) => x.name));
  * })(originalSchema);
  * ```
  *
+ * To use existing types from the schema you're extending, you can provide a
+ * function and use the {@link BaseSchemaMeta} passed into the function to use
+ * existing types in the schema.
+ *
+ * ```ts
+ * const originalSchema = new GraphQLSchema({ ...etc });
+ *
+ * const extendedSchema = extend((base) => ({
+ *   query: {
+ *     something: graphql.field({
+ *       type: base.object("Something"),
+ *       resolve() {
+ *         return { something: true };
+ *       },
+ *     }),
+ *   },
+ * }))(originalSchema);
+ * ```
+ *
+ * See {@link BaseSchemaMeta} for how to get other types from the schema
+ *
  * `extend` will currently throw an error if the query or mutation types are
- * used in other types like this
+ * used in other types like this. This will be allowed in a future version.
  *
  * ```graphql
  * type Query {
@@ -80,7 +101,7 @@ export function extend(
   extension:
     | Extension
     | readonly Extension[]
-    | ((current: BaseSchemaInfo) => Extension | readonly Extension[])
+    | ((base: BaseSchemaMeta) => Extension | readonly Extension[])
 ): (schema: GraphQLSchema) => GraphQLSchema {
   return (schema) => {
     const getType = (name: string) => {
@@ -334,16 +355,23 @@ function flattenExtensions(
 }
 
 /**
+ * Any
+ *
  * Note the distinct usages of `any` vs `unknown` is intentional.
  *
- * - The `unknown` used for the rootVal is because the root val isn't known and it
- *   should generally be used here because these fields are on the query and
- *   mutation types
+ * - The `unknown` used for the source type is because the source isn't known and
+ *   it shouldn't generally be used here because these fields are on the query
+ *   and mutation types
  * - The first `any` used for the `Args` type parameter is used because `Args` is
  *   invariant so only `Record<string, Arg<InputType, boolean>>` would work with
  *   it. The arguable unsafety here doesn't really matter because people will
  *   always use `graphql.field`
- * - The `any` in `OutputType` and the last type argument ``
+ * - The `any` in `OutputType` and the last type argument mean that a field that
+ *   requires any context can be provided. This is unsafe, the only way this
+ *   could arguably be made more "safe" is by making this unknown which would
+ *   requiring casting or make `extend` and etc. generic over a `Context` but
+ *   given this is immediately used on an arbitrary {@link GraphQLSchema} so the
+ *   type would immediately be thrown away, it would be pretty much pointless.
  */
 type FieldsOnAnything = {
   [key: string]: Field<unknown, any, OutputType<any>, string, any>;
@@ -363,7 +391,7 @@ export type Extension = {
    *   query: {
    *     isLoggedIn: graphql.field({
    *       type: graphql.Boolean,
-   *       resolve(rootVal, args, context, info) {
+   *       resolve(source, args, context, info) {
    *         // ...
    *       },
    *     }),
@@ -384,7 +412,7 @@ export type Extension = {
    *   mutation: {
    *     createPost: graphql.field({
    *       type: graphql.Boolean,
-   *       resolve(rootVal, args, context, info) {
+   *       resolve(source, args, context, info) {
    *         // ...
    *       },
    *     }),
@@ -407,15 +435,11 @@ export type Extension = {
 };
 
 /**
- * Information about the GraphQL schema that is being extended. Currently this
- * only exposes the {@link GraphQLSchema} object. In the future, this will be
- * extended to allow easily getting a type that exists in the base schema and
- * wrapping it in a `@graphql-ts/schema` type to use in the extension.
+ * This object contains the schema being extended and functions to get wrapped
  *
- * See the caveats mentioned {@link wrap} to learn about the lack of type safety
- * guarantees with these APIs
+ * Note that the just like {@link wrap}, all of the GraphQL types returned
  */
-export type BaseSchemaInfo = {
+export type BaseSchemaMeta = {
   schema: GraphQLSchema;
   /**
    * Gets an object type from the existing GraphQL schema and wraps it in an
@@ -455,7 +479,7 @@ export type BaseSchemaInfo = {
    *           type: base.inputObject("Something"),
    *         }),
    *       },
-   *       resolve(rootVal, { something }) {
+   *       resolve(source, { something }) {
    *         console.log(something);
    *         return "";
    *       },
@@ -484,7 +508,7 @@ export type BaseSchemaInfo = {
    *           type: base.enum("Something"),
    *         }),
    *       },
-   *       resolve(rootVal, { something }) {
+   *       resolve(source, { something }) {
    *         return something;
    *       },
    *     }),
@@ -560,7 +584,7 @@ export type BaseSchemaInfo = {
    *           type: base.scalar("JSON"),
    *         }),
    *       },
-   *       resolve(rootVal, { something }) {
+   *       resolve(source, { something }) {
    *         return something;
    *       },
    *     }),

packages/extend/src/wrap.ts

@@ -6,6 +6,8 @@
  * return GraphQL types that accept/can be used as any type and can be used with
  * any context. If you know more specific types for the GraphQL types, you
  * should cast them with `as`.
+ *
+ * @module
  */
 
 import {
@@ -51,7 +53,7 @@ export function object(
     kind: "object",
     graphQLType,
     __context: undefined as any,
-    __rootVal: undefined as any,
+    __source: undefined as any,
   };
 }
 
@@ -68,7 +70,7 @@ export function object(
  *   args: {
  *     something: graphql.arg({ type: someInputObjectType }),
  *   },
- *   resolve(rootVal, { something }) {
+ *   resolve(source, { something }) {
  *     console.log(something);
  *     // ...
  *   },
@@ -99,7 +101,7 @@ export function inputObject(
  *   args: {
  *     something: graphql.arg({ type: wrap.enum(someEnumType) }),
  *   },
- *   resolve(rootVal, { something }) {
+ *   resolve(source, { something }) {
  *     console.log(something);
  *     // ...
  *   },
@@ -150,7 +152,7 @@ export function union(
   return {
     kind: "union",
     __context: undefined as any,
-    __rootVal: undefined as any,
+    __source: undefined as any,
     graphQLType,
   };
 }
@@ -181,7 +183,7 @@ function interfaceType(
   return {
     kind: "interface",
     __context: undefined as any,
-    __rootVal: undefined as any,
+    __source: undefined as any,
     __fields: undefined as any,
     graphQLType,
   };

packages/schema/src/api-without-context/input.ts

@@ -112,7 +112,7 @@ export type InputObjectType<Fields extends { [key: string]: Arg<InputType> }> =
  *   args: {
  *     something: graphql.arg({ type: graphql.String }),
  *   },
- *   resolve(rootVal, { something }) {
+ *   resolve(source, { something }) {
  *     return something || somethingElse;
  *   },
  * });
@@ -145,7 +145,7 @@ export type InputObjectType<Fields extends { [key: string]: Arg<InputType> }> =
  *   args: {
  *     something: graphql.arg({ type: graphql.nonNull(graphql.String) }),
  *   },
- *   resolve(rootVal, { something }) {
+ *   resolve(source, { something }) {
  *     // `something` will always be a string
  *     return something;
  *   },
@@ -176,7 +176,7 @@ export type Arg<
  *   args: {
  *     something: graphql.arg({ type: graphql.String }),
  *   },
- *   resolve(rootVal, { something }) {
+ *   resolve(source, { something }) {
  *     return something || somethingElse;
  *   },
  * });

packages/schema/src/api-without-context/list-and-non-null.ts

@@ -28,7 +28,7 @@ export type ListType<Of extends Type<any>> = {
  * graphql.field({
  *   type: graphql.String,
  *   args: { thing: graphql.arg({ type: graphql.list(graphql.String) }) },
- *   resolve(rootVal, { thing }) {
+ *   resolve(source, { thing }) {
  *     const theThing: undefined | null | Array<string | null> = thing;
  *     return "";
  *   },
@@ -118,7 +118,7 @@ export type NonNullType<Of extends NullableType<any>> = {
  *     }),
  *   },
  *   type: graphql.String,
- *   resolve(rootVal, args) {
+ *   resolve(source, args) {
  *     // both of these will always be a string
  *     args.someNonNullAndRequiredArg;
  *     args.someNonNullButOptionalArg;
@@ -153,7 +153,7 @@ export type NonNullType<Of extends NullableType<any>> = {
  * ```ts
  * graphql.field({
  *   type: graphql.nonNull(graphql.String),
- *   resolve(rootVal, args) {
+ *   resolve(source, args) {
  *     return "something";
  *   },
  * });