Easier context binding with instantiation expressions

Author: emmatown

.changeset/purple-beers-mate.md

@@ -0,0 +1,35 @@
+---
+"@graphql-ts/schema": major
+---
+
+The `g` export exported from `@graphql-ts/schema` directly is now deprecated. Using `initG` is now the recommended way to use `@graphql-ts/schema` instead of the instance of `g` exported by `@graphql-ts/schema` or creating multiple files to setup `g` though using those is still possible.
+
+```ts
+import { GraphQLSchema } from "graphql";
+import { initG } from "@graphql-ts/schema";
+
+type Context = {
+  something: string;
+};
+
+const g = initG<Context>();
+type g<T> = initG<T>;
+
+const Query = g.object()({
+  name: "Query",
+  fields: {
+    something: g.field({
+      type: g.String,
+      resolve(_, __, context) {
+        return context.something;
+      },
+    }),
+  },
+});
+
+const schema = new GraphQLSchema({
+  query: Query,
+});
+```
+
+All types available at `g.*` like `g.ObjectType<Source>` can written instead like `g<typeof g.object<Source>>`/`GObjectType<Source, Context>` instead of being accessible directly on `g`.

packages/schema/README.md

@@ -6,16 +6,45 @@ constructing GraphQL Schemas while avoiding type-generation, [declaration mergin
 and [decorators](https://www.typescriptlang.org/docs/handbook/decorators.html).
 
 ```ts
-import { g } from "@graphql-ts/schema";
+import { initG } from "@graphql-ts/schema";
 import { GraphQLSchema, graphql } from "graphql";
 
+type Context = {
+  loadPerson: (id: string) => Person;
+  loadFriends: (id: string) => Person[];
+};
+const g = initG<Context>();
+type g<T> = initG<T>;
+
+type Person = {
+  id: string;
+  name: string;
+};
+
+const Person: g<typeof g.object<Person>> = g.object<Person>()({
+  name: "Person",
+  fields: () => ({
+    id: g.field({ type: g.ID }),
+    name: g.field({ type: g.String }),
+    friends: g.field({
+      type: g.list(Person),
+      resolve(source, _, context) {
+        return context.loadFriends(source.id);
+      },
+    }),
+  }),
+});
+
 const Query = g.object()({
   name: "Query",
   fields: {
-    hello: g.field({
-      type: g.String,
-      resolve() {
-        return "Hello!";
+    person: g.field({
+      type: Person,
+      args: {
+        id: g.arg({ type: g.ID }),
+      },
+      resolve(_, args, context) {
+        return context.loadPerson(args.id);
       },
     }),
   },
@@ -25,13 +54,37 @@ const schema = new GraphQLSchema({
   query: Query,
 });
 
+const people = new Map<string, Person>([
+  ["1", { id: "1", name: "Alice" }],
+  ["2", { id: "2", name: "Bob" }],
+]);
+const friends = new Map<string, string[]>([
+  ["1", ["2"]],
+  ["2", ["1"]],
+]);
+
 graphql({
   source: `
-    query {
-      hello
-    }
-  `,
+      query {
+        person(id: "1") {
+          id
+          name
+          friends {
+            id
+            name
+          }
+        }
+      }
+    `,
   schema,
+  context: {
+    loadPerson: (id) => people.get(id),
+    loadFriends: (id) => {
+      return (friends.get(id) ?? [])
+        .map((id) => people.get(id))
+        .filter((person) => person !== undefined);
+    },
+  },
 }).then((result) => {
   console.log(result);
 });

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

@@ -1,4 +1,4 @@
-export {
+import {
   arg,
   inputObject,
   Boolean,
@@ -8,10 +8,24 @@ export {
   String,
   list,
   nonNull,
-  enum,
+  enum as enumType,
   enumValues,
   scalar,
 } from "../api-with-context/api-with-context";
+export {
+  arg,
+  inputObject,
+  Boolean,
+  Float,
+  ID,
+  Int,
+  String,
+  list,
+  nonNull,
+  enumType as enum,
+  enumValues,
+  scalar,
+};
 export type {
   InferValueFromOutputType,
   InferValueFromArg,
@@ -32,26 +46,38 @@ import type {
   GType,
 } from "../types";
 
-/** @deprecated Use {@link GEnumType} instead */
+/**
+ * @deprecated Use {@link GEnumType} or {@link enumType `g<typeof g.enum<...>>`}
+ *   instead
+ */
 export type EnumType<Values extends { [key: string]: unknown }> =
   GEnumType<Values>;
-/** @deprecated Use {@link GArg} instead */
+/** @deprecated Use {@link GArg} or {@link arg `g<typeof g.arg<...>>`} instead */
 export type Arg<
   Type extends GInputType,
   HasDefaultValue extends boolean = boolean,
 > = GArg<Type, HasDefaultValue>;
-/** @deprecated Use {@link GList} instead */
+/** @deprecated Use {@link GList} or {@link list `g<typeof g.list<...>>`} instead */
 export type ListType<Of extends GType<any>> = GList<Of>;
-/** @deprecated Use {@link GNonNull} instead */
+/**
+ * @deprecated Use {@link GNonNull} or {@link nonNull `g<typeof g.nonNull<...>>`}
+ *   instead
+ */
 export type NonNullType<Of extends GNullableType<any>> = GNonNull<Of>;
 
-/** @deprecated Use {@link GScalarType} instead */
+/**
+ * @deprecated Use {@link GScalarType} or {@link scalar `g<typeof g.scalar<...>>`}
+ *   instead
+ */
 export type ScalarType<Internal, External = Internal> = GScalarType<
   Internal,
   External
 >;
 
-/** @deprecated Use {@link GInputObjectType} instead */
+/**
+ * @deprecated Use {@link GInputObjectType} or
+ *   {@link inputObject `g<typeof g.inputObject<...>>`} instead
+ */
 export type InputObjectType<
   Fields extends {
     [key: string]: IsOneOf extends true

packages/schema/src/index.ts

@@ -7,16 +7,45 @@
  * [decorators](https://www.typescriptlang.org/docs/handbook/decorators.html).
  *
  * ```ts
- * import { g } from "@graphql-ts/schema";
+ * import { initG } from "@graphql-ts/schema";
  * import { GraphQLSchema, graphql } from "graphql";
  *
+ * type Context = {
+ *   loadPerson: (id: string) => Person;
+ *   loadFriends: (id: string) => Person[];
+ * };
+ * const g = initG<Context>();
+ * type g<T> = initG<T>;
+ *
+ * type Person = {
+ *   id: string;
+ *   name: string;
+ * };
+ *
+ * const Person: g<typeof g.object<Person>> = g.object<Person>()({
+ *   name: "Person",
+ *   fields: () => ({
+ *     id: g.field({ type: g.ID }),
+ *     name: g.field({ type: g.String }),
+ *     friends: g.field({
+ *       type: g.list(Person),
+ *       resolve(source, _, context) {
+ *         return context.loadFriends(source.id);
+ *       },
+ *     }),
+ *   }),
+ * });
+ *
  * const Query = g.object()({
  *   name: "Query",
  *   fields: {
- *     hello: g.field({
- *       type: g.String,
- *       resolve() {
- *         return "Hello!";
+ *     person: g.field({
+ *       type: Person,
+ *       args: {
+ *         id: g.arg({ type: g.ID }),
+ *       },
+ *       resolve(_, args, context) {
+ *         return context.loadPerson(args.id);
  *       },
  *     }),
  *   },
@@ -26,22 +55,47 @@
  *   query: Query,
  * });
  *
+ * const people = new Map<string, Person>([
+ *   ["1", { id: "1", name: "Alice" }],
+ *   ["2", { id: "2", name: "Bob" }],
+ * ]);
+ * const friends = new Map<string, string[]>([
+ *   ["1", ["2"]],
+ *   ["2", ["1"]],
+ * ]);
+ *
  * graphql({
  *   source: `
- *     query {
- *       hello
- *     }
- *   `,
+ *       query {
+ *         person(id: "1") {
+ *           id
+ *           name
+ *           friends {
+ *             id
+ *             name
+ *           }
+ *         }
+ *       }
+ *     `,
  *   schema,
+ *   context: {
+ *     loadPerson: (id) => people.get(id),
+ *     loadFriends: (id) => {
+ *       return (friends.get(id) ?? [])
+ *         .map((id) => people.get(id))
+ *         .filter((person) => person !== undefined);
+ *     },
+ *   },
  * }).then((result) => {
  *   console.log(result);
  * });
  * ```
  *
  * @module
  */
-export * as g from "./schema-api";
-export { initG, type GWithContext } from "./output";
+import { initG, type GWithContext } from "./output";
+export { initG };
+export type { GWithContext };
 
 export {
   GObjectType,
@@ -67,6 +121,14 @@ export {
   type InferValueFromArgs,
   type InferValueFromInputType,
 } from "./types";
+/**
+ * @deprecated Use {@link initG} bound to a specific context instead of the this
+ *   `g` bound to an unknown context
+ */
+declare module "./schema-api" {}
+export type g<T> = initG<T>;
+export * as g from "./schema-api";
+
 export type {
   Arg,
   EnumType,