@aws-amplify/api-graphql 3.4.11 → 3.4.12-api-v6.2fd20b7.0

package/lib/internals/index.d.ts

@@ -1 +1,2 @@
 export { InternalGraphQLAPI, InternalGraphQLAPIClass, } from './InternalGraphQLAPI';
+export { graphql } from './v6';

package/lib/internals/index.js

@@ -5,4 +5,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var InternalGraphQLAPI_1 = require("./InternalGraphQLAPI");
 exports.InternalGraphQLAPI = InternalGraphQLAPI_1.InternalGraphQLAPI;
 exports.InternalGraphQLAPIClass = InternalGraphQLAPI_1.InternalGraphQLAPIClass;
+var v6_1 = require("./v6");
+exports.graphql = v6_1.graphql;
 //# sourceMappingURL=index.js.map

package/lib/internals/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/internals/index.ts"],"names":[],"mappings":";;AAAA,qEAAqE;AACrE,sCAAsC;AACtC,2DAG8B;AAF7B,kDAAA,kBAAkB,CAAA;AAClB,uDAAA,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/internals/index.ts"],"names":[],"mappings":";;AAAA,qEAAqE;AACrE,sCAAsC;AACtC,2DAG8B;AAF7B,kDAAA,kBAAkB,CAAA;AAClB,uDAAA,uBAAuB,CAAA;AAGxB,2BAA+B;AAAtB,uBAAA,OAAO,CAAA"}

package/lib/internals/v6.d.ts

@@ -0,0 +1,89 @@
+import { GraphQLOptionsV6, GraphQLResponseV6 } from '../types';
+/**
+ * Invokes graphql operations against a graphql service, providing correct input and
+ * output types if Amplify-generated graphql from a recent version of the CLI/codegen
+ * are used *or* correct typing is provided via the type argument.
+ *
+ * Amplify-generated "branded" graphql queries will look similar to this:
+ *
+ * ```ts
+ *                               //
+ *                               // |-- branding
+ *                               // v
+ * export const getModel = `...` as GeneratedQuery<
+ * 	GetModelQueryVariables,
+ * 	GetModelQuery
+ * >;
+ * ```
+ *
+ * If this branding is not in your generated graphql, update to a newer version of
+ * CLI/codegen and regenerate your graphql using `amplify codegen`.
+ *
+ * ## Using Amplify-generated graphql
+ *
+ * ```ts
+ * import * as queries from './graphql/queries';
+ *
+ * //
+ * //    |-- correctly typed graphql response containing a Widget
+ * //    v
+ * const queryResult = await graphql({
+ * 	query: queries.getWidget,
+ * 	variables: {
+ * 		id: "abc", // <-- type hinted/enforced
+ * 	},
+ * });
+ *
+ * //
+ * //    |-- a correctly typed Widget
+ * //    v
+ * const fetchedWidget = queryResult.data?.getWidget!;
+ * ```
+ *
+ * ## Custom input + result types
+ *
+ * To provide input types (`variables`) and result types:
+ *
+ * ```ts
+ * type GetById_NameOnly = {
+ * 	variables: {
+ * 		id: string
+ * 	},
+ * 	result: Promise<{
+ * 		data: { getWidget: { name: string } }
+ * 	}>
+ * }
+ *
+ * //
+ * //    |-- type is GetById_NameOnly["result"]
+ * //    v
+ * const result = graphql<GetById_NameOnly>({
+ * 	query: "...",
+ * 	variables: { id: "abc" }  // <-- type of GetById_NameOnly["variables"]
+ * });
+ * ```
+ *
+ * ## Custom result type only
+ *
+ * To specify result types only, use a type that is *not* in the `{variables, result}` shape:
+ *
+ * ```ts
+ * type MyResultType = Promise<{
+ * 	data: {
+ * 		getWidget: { name: string }
+ * 	}
+ * }>
+ *
+ * //
+ * //    |-- type is MyResultType
+ * //    v
+ * const result = graphql<MyResultType>({query: "..."});
+ * ```
+ *
+ * @param options
+ * @param additionalHeaders
+ */
+export declare function graphql<FALLBACK_TYPES = unknown, TYPED_GQL_STRING extends string = string>(options: GraphQLOptionsV6<FALLBACK_TYPES, TYPED_GQL_STRING>, additionalHeaders?: {
+    [key: string]: string;
+}): GraphQLResponseV6<FALLBACK_TYPES, TYPED_GQL_STRING>;
+export { GraphQLOptionsV6, GraphQLResponseV6 };

package/lib/internals/v6.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+var GraphQLAPI_1 = require("../GraphQLAPI");
+/**
+ * Invokes graphql operations against a graphql service, providing correct input and
+ * output types if Amplify-generated graphql from a recent version of the CLI/codegen
+ * are used *or* correct typing is provided via the type argument.
+ *
+ * Amplify-generated "branded" graphql queries will look similar to this:
+ *
+ * ```ts
+ *                               //
+ *                               // |-- branding
+ *                               // v
+ * export const getModel = `...` as GeneratedQuery<
+ * 	GetModelQueryVariables,
+ * 	GetModelQuery
+ * >;
+ * ```
+ *
+ * If this branding is not in your generated graphql, update to a newer version of
+ * CLI/codegen and regenerate your graphql using `amplify codegen`.
+ *
+ * ## Using Amplify-generated graphql
+ *
+ * ```ts
+ * import * as queries from './graphql/queries';
+ *
+ * //
+ * //    |-- correctly typed graphql response containing a Widget
+ * //    v
+ * const queryResult = await graphql({
+ * 	query: queries.getWidget,
+ * 	variables: {
+ * 		id: "abc", // <-- type hinted/enforced
+ * 	},
+ * });
+ *
+ * //
+ * //    |-- a correctly typed Widget
+ * //    v
+ * const fetchedWidget = queryResult.data?.getWidget!;
+ * ```
+ *
+ * ## Custom input + result types
+ *
+ * To provide input types (`variables`) and result types:
+ *
+ * ```ts
+ * type GetById_NameOnly = {
+ * 	variables: {
+ * 		id: string
+ * 	},
+ * 	result: Promise<{
+ * 		data: { getWidget: { name: string } }
+ * 	}>
+ * }
+ *
+ * //
+ * //    |-- type is GetById_NameOnly["result"]
+ * //    v
+ * const result = graphql<GetById_NameOnly>({
+ * 	query: "...",
+ * 	variables: { id: "abc" }  // <-- type of GetById_NameOnly["variables"]
+ * });
+ * ```
+ *
+ * ## Custom result type only
+ *
+ * To specify result types only, use a type that is *not* in the `{variables, result}` shape:
+ *
+ * ```ts
+ * type MyResultType = Promise<{
+ * 	data: {
+ * 		getWidget: { name: string }
+ * 	}
+ * }>
+ *
+ * //
+ * //    |-- type is MyResultType
+ * //    v
+ * const result = graphql<MyResultType>({query: "..."});
+ * ```
+ *
+ * @param options
+ * @param additionalHeaders
+ */
+function graphql(options, additionalHeaders) {
+    /**
+     * The correctness of these typings depends on correct string branding or overrides.
+     * Neither of these can actually be validated at runtime. Hence, we don't perform
+     * any validation or type-guarding here.
+     */
+    var result = GraphQLAPI_1.GraphQLAPI.graphql(options, additionalHeaders);
+    return result;
+}
+exports.graphql = graphql;
+//# sourceMappingURL=v6.js.map

package/lib/internals/v6.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v6.js","sourceRoot":"","sources":["../../src/internals/v6.ts"],"names":[],"mappings":";;AAAA,qEAAqE;AACrE,sCAAsC;AACtC,4CAA2C;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,SAAgB,OAAO,CAItB,OAA2D,EAC3D,iBAA6C;IAE7C;;;;OAIG;IACH,IAAM,MAAM,GAAG,uBAAU,CAAC,OAAO,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC9D,OAAO,MAAa,CAAC;AACtB,CAAC;AAdD,0BAcC"}

package/lib/types/index.d.ts

@@ -2,6 +2,11 @@ import { Source, DocumentNode, GraphQLError } from 'graphql';
 export { OperationTypeNode } from 'graphql';
 import { GRAPHQL_AUTH_MODE } from '@aws-amplify/auth';
 export { GRAPHQL_AUTH_MODE };
+import { Observable } from 'zen-observable-ts';
+import { AWSAppSyncRealTimeProvider } from '@aws-amplify/pubsub';
+/**
+ * Loose/Unknown options for raw GraphQLAPICategory `graphql()`.
+ */
 export interface GraphQLOptions {
     query: string | DocumentNode;
     variables?: object;
@@ -19,6 +24,56 @@ export interface GraphQLResult<T = object> {
         [key: string]: any;
     };
 }
+declare const queryType: unique symbol;
+export declare type GraphQLQuery<T> = T & {
+    readonly [queryType]: 'query';
+};
+export declare type GraphQLSubscription<T> = T & {
+    readonly [queryType]: 'subscription';
+};
+/**
+ * The return value from a `graphql({query})` call when `query` is a subscription.
+ *
+ * ```ts
+ * //               |-- You are here
+ * //               v
+ * const subResult: GraphqlSubscriptionResult<T> = client.graphql({
+ * 	query: onCreateWidget
+ * });
+ *
+ * const sub = subResult.subscribe({
+ * 	//
+ * 	//            |-- You are here
+ * 	//            v
+ * 	next(message: GraphqlSubscriptionMessage<OnCreateWidgetSubscription>) {
+ * 		handle(message.value);  // <-- type OnCreateWidgetSubscription
+ * 	}
+ * })
+ * ```
+ */
+export declare type GraphqlSubscriptionResult<T> = Observable<GraphqlSubscriptionMessage<T>>;
+/**
+ * The shape of messages passed to `next()` from a graphql subscription. E.g.,
+ *
+ * ```ts
+ * const sub = client.graphql({
+ * 	query: onCreateWidget,
+ * }).subscribe({
+ * 	//
+ * 	//            |-- You are here
+ * 	//            v
+ * 	next(message: GraphqlSubscriptionMessage<OnCreateWidgetSubscription>) {
+ * 		handle(message.value);  // <-- type OnCreateWidgetSubscription
+ * 	}
+ * })
+ * ```
+ */
+export declare type GraphqlSubscriptionMessage<T> = {
+    provider: AWSAppSyncRealTimeProvider;
+    value: {
+        data?: T;
+    };
+};
 export declare enum GraphQLAuthError {
     NO_API_KEY = "No api-key configured",
     NO_CURRENT_USER = "No current user",
@@ -31,3 +86,117 @@ export declare enum GraphQLAuthError {
  * @see: https://graphql.org/graphql-js/language/#parse
  */
 export declare type GraphQLOperation = Source | string;
+/**
+ * API V6 `graphql({options})` type that can leverage branded graphql `query`
+ * objects and fallback types.
+ */
+export interface GraphQLOptionsV6<FALLBACK_TYPES = unknown, TYPED_GQL_STRING extends string = string> {
+    query: TYPED_GQL_STRING | DocumentNode;
+    variables?: GraphQLVariablesV6<FALLBACK_TYPES, TYPED_GQL_STRING>;
+    authMode?: keyof typeof GRAPHQL_AUTH_MODE;
+    authToken?: string;
+    /**
+     * @deprecated This property should not be used
+     */
+    userAgentSuffix?: string;
+}
+/**
+ * Result type for `graphql()` operations that don't include any specific
+ * type information. The result could be either a `Promise` or `Subscription`.
+ *
+ * Invoking code should either cast the result or use `?` and `!` operators to
+ * navigate the result objects.
+ */
+export declare type UnknownGraphQLResponse = Promise<GraphQLResult<any>> | GraphqlSubscriptionResult<any>;
+/**
+ * The expected type for `variables` in a V6 `graphql()` operation with
+ * respect to the given `FALLBACK_TYPES` and `TYPED_GQL_STRING`.
+ */
+export declare type GraphQLVariablesV6<FALLBACK_TYPES = unknown, TYPED_GQL_STRING extends string = string> = TYPED_GQL_STRING extends GeneratedQuery<infer IN, any> ? IN : TYPED_GQL_STRING extends GeneratedMutation<infer IN, any> ? IN : TYPED_GQL_STRING extends GeneratedSubscription<infer IN, any> ? IN : FALLBACK_TYPES extends GraphQLOperationType<infer IN, any> ? IN : any;
+/**
+ * The expected return type with respect to the given `FALLBACK_TYPE`
+ * and `TYPED_GQL_STRING`.
+ */
+export declare type GraphQLResponseV6<FALLBACK_TYPE = unknown, TYPED_GQL_STRING extends string = string> = TYPED_GQL_STRING extends GeneratedQuery<infer IN, infer QUERY_OUT> ? Promise<GraphQLResult<QUERY_OUT>> : TYPED_GQL_STRING extends GeneratedMutation<infer IN, infer MUTATION_OUT> ? Promise<GraphQLResult<MUTATION_OUT>> : TYPED_GQL_STRING extends GeneratedSubscription<infer IN, infer SUB_OUT> ? GraphqlSubscriptionResult<SUB_OUT> : FALLBACK_TYPE extends GraphQLQuery<infer T> ? Promise<GraphQLResult<FALLBACK_TYPE>> : FALLBACK_TYPE extends GraphQLSubscription<infer T> ? GraphqlSubscriptionResult<FALLBACK_TYPE> : FALLBACK_TYPE extends GraphQLOperationType<infer IN, infer CUSTOM_OUT> ? CUSTOM_OUT : UnknownGraphQLResponse;
+/**
+ * The shape customers can use to provide `T` to `graphql<T>()` to specify both
+ * `IN` and `OUT` types (the type of `variables` and the return type, respectively).
+ *
+ * I.E.,
+ *
+ * ```ts
+ * type MyVariablesType = { ... };
+ * type MyResultType = { ... };
+ * type MyOperationType = { variables: MyVariablesType, result: MyResultType };
+ *
+ * const result: MyResultType = graphql<MyOperationType>("graphql string", {
+ * 	variables: {
+ * 		// MyVariablesType
+ * 	}
+ * })
+ * ```
+ */
+export declare type GraphQLOperationType<IN extends {}, OUT extends {}> = {
+    variables: IN;
+    result: OUT;
+};
+/**
+ * Nominal type for branding generated graphql query operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const getWidget = `...` as GeneratedQuery<
+ * 	GetWidgetQueryVariables,
+ * 	GetWidgetQuery
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export declare type GeneratedQuery<InputType, OutputType> = string & {
+    __generatedQueryInput: InputType;
+    __generatedQueryOutput: OutputType;
+};
+/**
+ * Nominal type for branding generated graphql mutation operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const createWidget = `...` as GeneratedQuery<
+ * 	CreateWidgetMutationVariables,
+ * 	CreateWidgetMutation
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export declare type GeneratedMutation<InputType, OutputType> = string & {
+    __generatedMutationInput: InputType;
+    __generatedMutationOutput: OutputType;
+};
+/**
+ * Nominal type for branding generated graphql mutation operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const createWidget = `...` as GeneratedMutation<
+ * 	CreateWidgetMutationVariables,
+ * 	CreateWidgetMutation
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export declare type GeneratedSubscription<InputType, OutputType> = string & {
+    __generatedSubscriptionInput: InputType;
+    __generatedSubscriptionOutput: OutputType;
+};

package/lib/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;AAIA,0CAAsD;AAC7C,4BADA,wBAAiB,CACA;AAsB1B,IAAY,gBAMX;AAND,WAAY,gBAAgB;IAC3B,wDAAoC,CAAA;IACpC,uDAAmC,CAAA;IACnC,qDAAiC,CAAA;IACjC,yDAAqC,CAAA;IACrC,6DAAyC,CAAA;AAC1C,CAAC,EANW,gBAAgB,GAAhB,wBAAgB,KAAhB,wBAAgB,QAM3B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;AAIA,0CAAsD;AAC7C,4BADA,wBAAiB,CACA;AA+E1B,IAAY,gBAMX;AAND,WAAY,gBAAgB;IAC3B,wDAAoC,CAAA;IACpC,uDAAmC,CAAA;IACnC,qDAAiC,CAAA;IACjC,yDAAqC,CAAA;IACrC,6DAAyC,CAAA;AAC1C,CAAC,EANW,gBAAgB,GAAhB,wBAAgB,KAAhB,wBAAgB,QAM3B"}

package/lib-esm/internals/index.d.ts

@@ -1 +1,2 @@
 export { InternalGraphQLAPI, InternalGraphQLAPIClass, } from './InternalGraphQLAPI';
+export { graphql } from './v6';

package/lib-esm/internals/index.js

@@ -1,4 +1,5 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 export { InternalGraphQLAPI, InternalGraphQLAPIClass, } from './InternalGraphQLAPI';
+export { graphql } from './v6';
 //# sourceMappingURL=index.js.map

package/lib-esm/internals/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/internals/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,sCAAsC;AACtC,OAAO,EACN,kBAAkB,EAClB,uBAAuB,GACvB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/internals/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,sCAAsC;AACtC,OAAO,EACN,kBAAkB,EAClB,uBAAuB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC"}

package/lib-esm/internals/v6.d.ts

@@ -0,0 +1,89 @@
+import { GraphQLOptionsV6, GraphQLResponseV6 } from '../types';
+/**
+ * Invokes graphql operations against a graphql service, providing correct input and
+ * output types if Amplify-generated graphql from a recent version of the CLI/codegen
+ * are used *or* correct typing is provided via the type argument.
+ *
+ * Amplify-generated "branded" graphql queries will look similar to this:
+ *
+ * ```ts
+ *                               //
+ *                               // |-- branding
+ *                               // v
+ * export const getModel = `...` as GeneratedQuery<
+ * 	GetModelQueryVariables,
+ * 	GetModelQuery
+ * >;
+ * ```
+ *
+ * If this branding is not in your generated graphql, update to a newer version of
+ * CLI/codegen and regenerate your graphql using `amplify codegen`.
+ *
+ * ## Using Amplify-generated graphql
+ *
+ * ```ts
+ * import * as queries from './graphql/queries';
+ *
+ * //
+ * //    |-- correctly typed graphql response containing a Widget
+ * //    v
+ * const queryResult = await graphql({
+ * 	query: queries.getWidget,
+ * 	variables: {
+ * 		id: "abc", // <-- type hinted/enforced
+ * 	},
+ * });
+ *
+ * //
+ * //    |-- a correctly typed Widget
+ * //    v
+ * const fetchedWidget = queryResult.data?.getWidget!;
+ * ```
+ *
+ * ## Custom input + result types
+ *
+ * To provide input types (`variables`) and result types:
+ *
+ * ```ts
+ * type GetById_NameOnly = {
+ * 	variables: {
+ * 		id: string
+ * 	},
+ * 	result: Promise<{
+ * 		data: { getWidget: { name: string } }
+ * 	}>
+ * }
+ *
+ * //
+ * //    |-- type is GetById_NameOnly["result"]
+ * //    v
+ * const result = graphql<GetById_NameOnly>({
+ * 	query: "...",
+ * 	variables: { id: "abc" }  // <-- type of GetById_NameOnly["variables"]
+ * });
+ * ```
+ *
+ * ## Custom result type only
+ *
+ * To specify result types only, use a type that is *not* in the `{variables, result}` shape:
+ *
+ * ```ts
+ * type MyResultType = Promise<{
+ * 	data: {
+ * 		getWidget: { name: string }
+ * 	}
+ * }>
+ *
+ * //
+ * //    |-- type is MyResultType
+ * //    v
+ * const result = graphql<MyResultType>({query: "..."});
+ * ```
+ *
+ * @param options
+ * @param additionalHeaders
+ */
+export declare function graphql<FALLBACK_TYPES = unknown, TYPED_GQL_STRING extends string = string>(options: GraphQLOptionsV6<FALLBACK_TYPES, TYPED_GQL_STRING>, additionalHeaders?: {
+    [key: string]: string;
+}): GraphQLResponseV6<FALLBACK_TYPES, TYPED_GQL_STRING>;
+export { GraphQLOptionsV6, GraphQLResponseV6 };

package/lib-esm/internals/v6.js

@@ -0,0 +1,97 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { GraphQLAPI } from '../GraphQLAPI';
+/**
+ * Invokes graphql operations against a graphql service, providing correct input and
+ * output types if Amplify-generated graphql from a recent version of the CLI/codegen
+ * are used *or* correct typing is provided via the type argument.
+ *
+ * Amplify-generated "branded" graphql queries will look similar to this:
+ *
+ * ```ts
+ *                               //
+ *                               // |-- branding
+ *                               // v
+ * export const getModel = `...` as GeneratedQuery<
+ * 	GetModelQueryVariables,
+ * 	GetModelQuery
+ * >;
+ * ```
+ *
+ * If this branding is not in your generated graphql, update to a newer version of
+ * CLI/codegen and regenerate your graphql using `amplify codegen`.
+ *
+ * ## Using Amplify-generated graphql
+ *
+ * ```ts
+ * import * as queries from './graphql/queries';
+ *
+ * //
+ * //    |-- correctly typed graphql response containing a Widget
+ * //    v
+ * const queryResult = await graphql({
+ * 	query: queries.getWidget,
+ * 	variables: {
+ * 		id: "abc", // <-- type hinted/enforced
+ * 	},
+ * });
+ *
+ * //
+ * //    |-- a correctly typed Widget
+ * //    v
+ * const fetchedWidget = queryResult.data?.getWidget!;
+ * ```
+ *
+ * ## Custom input + result types
+ *
+ * To provide input types (`variables`) and result types:
+ *
+ * ```ts
+ * type GetById_NameOnly = {
+ * 	variables: {
+ * 		id: string
+ * 	},
+ * 	result: Promise<{
+ * 		data: { getWidget: { name: string } }
+ * 	}>
+ * }
+ *
+ * //
+ * //    |-- type is GetById_NameOnly["result"]
+ * //    v
+ * const result = graphql<GetById_NameOnly>({
+ * 	query: "...",
+ * 	variables: { id: "abc" }  // <-- type of GetById_NameOnly["variables"]
+ * });
+ * ```
+ *
+ * ## Custom result type only
+ *
+ * To specify result types only, use a type that is *not* in the `{variables, result}` shape:
+ *
+ * ```ts
+ * type MyResultType = Promise<{
+ * 	data: {
+ * 		getWidget: { name: string }
+ * 	}
+ * }>
+ *
+ * //
+ * //    |-- type is MyResultType
+ * //    v
+ * const result = graphql<MyResultType>({query: "..."});
+ * ```
+ *
+ * @param options
+ * @param additionalHeaders
+ */
+export function graphql(options, additionalHeaders) {
+    /**
+     * The correctness of these typings depends on correct string branding or overrides.
+     * Neither of these can actually be validated at runtime. Hence, we don't perform
+     * any validation or type-guarding here.
+     */
+    var result = GraphQLAPI.graphql(options, additionalHeaders);
+    return result;
+}
+//# sourceMappingURL=v6.js.map

package/lib-esm/internals/v6.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v6.js","sourceRoot":"","sources":["../../src/internals/v6.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,sCAAsC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,MAAM,UAAU,OAAO,CAItB,OAA2D,EAC3D,iBAA6C;IAE7C;;;;OAIG;IACH,IAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC9D,OAAO,MAAa,CAAC;AACtB,CAAC"}

package/lib-esm/types/index.d.ts

@@ -2,6 +2,11 @@ import { Source, DocumentNode, GraphQLError } from 'graphql';
 export { OperationTypeNode } from 'graphql';
 import { GRAPHQL_AUTH_MODE } from '@aws-amplify/auth';
 export { GRAPHQL_AUTH_MODE };
+import { Observable } from 'zen-observable-ts';
+import { AWSAppSyncRealTimeProvider } from '@aws-amplify/pubsub';
+/**
+ * Loose/Unknown options for raw GraphQLAPICategory `graphql()`.
+ */
 export interface GraphQLOptions {
     query: string | DocumentNode;
     variables?: object;
@@ -19,6 +24,56 @@ export interface GraphQLResult<T = object> {
         [key: string]: any;
     };
 }
+declare const queryType: unique symbol;
+export declare type GraphQLQuery<T> = T & {
+    readonly [queryType]: 'query';
+};
+export declare type GraphQLSubscription<T> = T & {
+    readonly [queryType]: 'subscription';
+};
+/**
+ * The return value from a `graphql({query})` call when `query` is a subscription.
+ *
+ * ```ts
+ * //               |-- You are here
+ * //               v
+ * const subResult: GraphqlSubscriptionResult<T> = client.graphql({
+ * 	query: onCreateWidget
+ * });
+ *
+ * const sub = subResult.subscribe({
+ * 	//
+ * 	//            |-- You are here
+ * 	//            v
+ * 	next(message: GraphqlSubscriptionMessage<OnCreateWidgetSubscription>) {
+ * 		handle(message.value);  // <-- type OnCreateWidgetSubscription
+ * 	}
+ * })
+ * ```
+ */
+export declare type GraphqlSubscriptionResult<T> = Observable<GraphqlSubscriptionMessage<T>>;
+/**
+ * The shape of messages passed to `next()` from a graphql subscription. E.g.,
+ *
+ * ```ts
+ * const sub = client.graphql({
+ * 	query: onCreateWidget,
+ * }).subscribe({
+ * 	//
+ * 	//            |-- You are here
+ * 	//            v
+ * 	next(message: GraphqlSubscriptionMessage<OnCreateWidgetSubscription>) {
+ * 		handle(message.value);  // <-- type OnCreateWidgetSubscription
+ * 	}
+ * })
+ * ```
+ */
+export declare type GraphqlSubscriptionMessage<T> = {
+    provider: AWSAppSyncRealTimeProvider;
+    value: {
+        data?: T;
+    };
+};
 export declare enum GraphQLAuthError {
     NO_API_KEY = "No api-key configured",
     NO_CURRENT_USER = "No current user",
@@ -31,3 +86,117 @@ export declare enum GraphQLAuthError {
  * @see: https://graphql.org/graphql-js/language/#parse
  */
 export declare type GraphQLOperation = Source | string;
+/**
+ * API V6 `graphql({options})` type that can leverage branded graphql `query`
+ * objects and fallback types.
+ */
+export interface GraphQLOptionsV6<FALLBACK_TYPES = unknown, TYPED_GQL_STRING extends string = string> {
+    query: TYPED_GQL_STRING | DocumentNode;
+    variables?: GraphQLVariablesV6<FALLBACK_TYPES, TYPED_GQL_STRING>;
+    authMode?: keyof typeof GRAPHQL_AUTH_MODE;
+    authToken?: string;
+    /**
+     * @deprecated This property should not be used
+     */
+    userAgentSuffix?: string;
+}
+/**
+ * Result type for `graphql()` operations that don't include any specific
+ * type information. The result could be either a `Promise` or `Subscription`.
+ *
+ * Invoking code should either cast the result or use `?` and `!` operators to
+ * navigate the result objects.
+ */
+export declare type UnknownGraphQLResponse = Promise<GraphQLResult<any>> | GraphqlSubscriptionResult<any>;
+/**
+ * The expected type for `variables` in a V6 `graphql()` operation with
+ * respect to the given `FALLBACK_TYPES` and `TYPED_GQL_STRING`.
+ */
+export declare type GraphQLVariablesV6<FALLBACK_TYPES = unknown, TYPED_GQL_STRING extends string = string> = TYPED_GQL_STRING extends GeneratedQuery<infer IN, any> ? IN : TYPED_GQL_STRING extends GeneratedMutation<infer IN, any> ? IN : TYPED_GQL_STRING extends GeneratedSubscription<infer IN, any> ? IN : FALLBACK_TYPES extends GraphQLOperationType<infer IN, any> ? IN : any;
+/**
+ * The expected return type with respect to the given `FALLBACK_TYPE`
+ * and `TYPED_GQL_STRING`.
+ */
+export declare type GraphQLResponseV6<FALLBACK_TYPE = unknown, TYPED_GQL_STRING extends string = string> = TYPED_GQL_STRING extends GeneratedQuery<infer IN, infer QUERY_OUT> ? Promise<GraphQLResult<QUERY_OUT>> : TYPED_GQL_STRING extends GeneratedMutation<infer IN, infer MUTATION_OUT> ? Promise<GraphQLResult<MUTATION_OUT>> : TYPED_GQL_STRING extends GeneratedSubscription<infer IN, infer SUB_OUT> ? GraphqlSubscriptionResult<SUB_OUT> : FALLBACK_TYPE extends GraphQLQuery<infer T> ? Promise<GraphQLResult<FALLBACK_TYPE>> : FALLBACK_TYPE extends GraphQLSubscription<infer T> ? GraphqlSubscriptionResult<FALLBACK_TYPE> : FALLBACK_TYPE extends GraphQLOperationType<infer IN, infer CUSTOM_OUT> ? CUSTOM_OUT : UnknownGraphQLResponse;
+/**
+ * The shape customers can use to provide `T` to `graphql<T>()` to specify both
+ * `IN` and `OUT` types (the type of `variables` and the return type, respectively).
+ *
+ * I.E.,
+ *
+ * ```ts
+ * type MyVariablesType = { ... };
+ * type MyResultType = { ... };
+ * type MyOperationType = { variables: MyVariablesType, result: MyResultType };
+ *
+ * const result: MyResultType = graphql<MyOperationType>("graphql string", {
+ * 	variables: {
+ * 		// MyVariablesType
+ * 	}
+ * })
+ * ```
+ */
+export declare type GraphQLOperationType<IN extends {}, OUT extends {}> = {
+    variables: IN;
+    result: OUT;
+};
+/**
+ * Nominal type for branding generated graphql query operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const getWidget = `...` as GeneratedQuery<
+ * 	GetWidgetQueryVariables,
+ * 	GetWidgetQuery
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export declare type GeneratedQuery<InputType, OutputType> = string & {
+    __generatedQueryInput: InputType;
+    __generatedQueryOutput: OutputType;
+};
+/**
+ * Nominal type for branding generated graphql mutation operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const createWidget = `...` as GeneratedQuery<
+ * 	CreateWidgetMutationVariables,
+ * 	CreateWidgetMutation
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export declare type GeneratedMutation<InputType, OutputType> = string & {
+    __generatedMutationInput: InputType;
+    __generatedMutationOutput: OutputType;
+};
+/**
+ * Nominal type for branding generated graphql mutation operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const createWidget = `...` as GeneratedMutation<
+ * 	CreateWidgetMutationVariables,
+ * 	CreateWidgetMutation
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export declare type GeneratedSubscription<InputType, OutputType> = string & {
+    __generatedSubscriptionInput: InputType;
+    __generatedSubscriptionOutput: OutputType;
+};

package/lib-esm/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAsB7B,MAAM,CAAN,IAAY,gBAMX;AAND,WAAY,gBAAgB;IAC3B,wDAAoC,CAAA;IACpC,uDAAmC,CAAA;IACnC,qDAAiC,CAAA;IACjC,yDAAqC,CAAA;IACrC,6DAAyC,CAAA;AAC1C,CAAC,EANW,gBAAgB,KAAhB,gBAAgB,QAM3B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,CAAC;AA+E7B,MAAM,CAAN,IAAY,gBAMX;AAND,WAAY,gBAAgB;IAC3B,wDAAoC,CAAA;IACpC,uDAAmC,CAAA;IACnC,qDAAiC,CAAA;IACjC,yDAAqC,CAAA;IACrC,6DAAyC,CAAA;AAC1C,CAAC,EANW,gBAAgB,KAAhB,gBAAgB,QAM3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-amplify/api-graphql",
-  "version": "3.4.11",
+  "version": "3.4.12-api-v6.2fd20b7.0+2fd20b7",
   "description": "Api-graphql category of aws-amplify",
   "main": "./lib/index.js",
   "module": "./lib-esm/index.js",
@@ -50,11 +50,11 @@
     "internals"
   ],
   "dependencies": {
-    "@aws-amplify/api-rest": "3.5.5",
-    "@aws-amplify/auth": "5.6.5",
-    "@aws-amplify/cache": "5.1.11",
-    "@aws-amplify/core": "5.8.5",
-    "@aws-amplify/pubsub": "5.5.5",
+    "@aws-amplify/api-rest": "3.5.6-api-v6.2fd20b7.0+2fd20b7",
+    "@aws-amplify/auth": "5.6.6-api-v6.2fd20b7.0+2fd20b7",
+    "@aws-amplify/cache": "5.1.12-api-v6.2fd20b7.0+2fd20b7",
+    "@aws-amplify/core": "5.8.6-api-v6.2fd20b7.0+2fd20b7",
+    "@aws-amplify/pubsub": "5.5.6-api-v6.2fd20b7.0+2fd20b7",
     "graphql": "15.8.0",
     "tslib": "^1.8.0",
     "uuid": "^3.2.1",
@@ -65,13 +65,13 @@
       "name": "API (GraphQL client)",
       "path": "./lib-esm/index.js",
       "import": "{ Amplify, GraphQLAPI }",
-      "limit": "89.52 kB"
+      "limit": "91.7 kB"
     }
   ],
   "jest": {
     "globals": {
       "ts-jest": {
-        "diagnostics": false,
+        "diagnostics": true,
         "tsConfig": {
           "lib": [
             "es5",
@@ -88,6 +88,10 @@
       "^.+\\.(js|jsx|ts|tsx)$": "ts-jest"
     },
     "testRegex": "(/__tests__/.*|\\.(test|spec))\\.(tsx?|jsx?)$",
+    "testPathIgnorePatterns": [
+      "__tests__/fixtures",
+      "__tests__/utils"
+    ],
     "moduleFileExtensions": [
       "ts",
       "tsx",
@@ -112,5 +116,5 @@
       "lib-esm"
     ]
   },
-  "gitHead": "c3a06153e3ffe05dd65485a22b1f99aabe9b3d83"
+  "gitHead": "2fd20b795c222663f811d4daf68a475497127fd7"
 }

package/src/internals/index.ts

@@ -4,3 +4,5 @@ export {
 	InternalGraphQLAPI,
 	InternalGraphQLAPIClass,
 } from './InternalGraphQLAPI';
+
+export { graphql } from './v6';

package/src/internals/v6.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { GraphQLAPI } from '../GraphQLAPI';
+import { GraphQLOptionsV6, GraphQLResponseV6 } from '../types';
+
+/**
+ * Invokes graphql operations against a graphql service, providing correct input and
+ * output types if Amplify-generated graphql from a recent version of the CLI/codegen
+ * are used *or* correct typing is provided via the type argument.
+ *
+ * Amplify-generated "branded" graphql queries will look similar to this:
+ *
+ * ```ts
+ *                               //
+ *                               // |-- branding
+ *                               // v
+ * export const getModel = `...` as GeneratedQuery<
+ * 	GetModelQueryVariables,
+ * 	GetModelQuery
+ * >;
+ * ```
+ *
+ * If this branding is not in your generated graphql, update to a newer version of
+ * CLI/codegen and regenerate your graphql using `amplify codegen`.
+ *
+ * ## Using Amplify-generated graphql
+ *
+ * ```ts
+ * import * as queries from './graphql/queries';
+ *
+ * //
+ * //    |-- correctly typed graphql response containing a Widget
+ * //    v
+ * const queryResult = await graphql({
+ * 	query: queries.getWidget,
+ * 	variables: {
+ * 		id: "abc", // <-- type hinted/enforced
+ * 	},
+ * });
+ *
+ * //
+ * //    |-- a correctly typed Widget
+ * //    v
+ * const fetchedWidget = queryResult.data?.getWidget!;
+ * ```
+ *
+ * ## Custom input + result types
+ *
+ * To provide input types (`variables`) and result types:
+ *
+ * ```ts
+ * type GetById_NameOnly = {
+ * 	variables: {
+ * 		id: string
+ * 	},
+ * 	result: Promise<{
+ * 		data: { getWidget: { name: string } }
+ * 	}>
+ * }
+ *
+ * //
+ * //    |-- type is GetById_NameOnly["result"]
+ * //    v
+ * const result = graphql<GetById_NameOnly>({
+ * 	query: "...",
+ * 	variables: { id: "abc" }  // <-- type of GetById_NameOnly["variables"]
+ * });
+ * ```
+ *
+ * ## Custom result type only
+ *
+ * To specify result types only, use a type that is *not* in the `{variables, result}` shape:
+ *
+ * ```ts
+ * type MyResultType = Promise<{
+ * 	data: {
+ * 		getWidget: { name: string }
+ * 	}
+ * }>
+ *
+ * //
+ * //    |-- type is MyResultType
+ * //    v
+ * const result = graphql<MyResultType>({query: "..."});
+ * ```
+ *
+ * @param options
+ * @param additionalHeaders
+ */
+export function graphql<
+	FALLBACK_TYPES = unknown,
+	TYPED_GQL_STRING extends string = string
+>(
+	options: GraphQLOptionsV6<FALLBACK_TYPES, TYPED_GQL_STRING>,
+	additionalHeaders?: { [key: string]: string }
+): GraphQLResponseV6<FALLBACK_TYPES, TYPED_GQL_STRING> {
+	/**
+	 * The correctness of these typings depends on correct string branding or overrides.
+	 * Neither of these can actually be validated at runtime. Hence, we don't perform
+	 * any validation or type-guarding here.
+	 */
+	const result = GraphQLAPI.graphql(options, additionalHeaders);
+	return result as any;
+}
+
+export { GraphQLOptionsV6, GraphQLResponseV6 };

package/src/types/index.ts

@@ -1,11 +1,15 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { Source, DocumentNode, GraphQLError, OperationTypeNode } from 'graphql';
+import { Source, DocumentNode, GraphQLError } from 'graphql';
 export { OperationTypeNode } from 'graphql';
 import { GRAPHQL_AUTH_MODE } from '@aws-amplify/auth';
 export { GRAPHQL_AUTH_MODE };
-import { CustomUserAgentDetails } from '@aws-amplify/core';
+import { Observable } from 'zen-observable-ts';
+import { AWSAppSyncRealTimeProvider } from '@aws-amplify/pubsub';
 
+/**
+ * Loose/Unknown options for raw GraphQLAPICategory `graphql()`.
+ */
 export interface GraphQLOptions {
 	query: string | DocumentNode;
 	variables?: object;
@@ -25,6 +29,59 @@ export interface GraphQLResult<T = object> {
 	};
 }
 
+// Opaque type used for determining the graphql query type
+declare const queryType: unique symbol;
+
+export type GraphQLQuery<T> = T & { readonly [queryType]: 'query' };
+export type GraphQLSubscription<T> = T & {
+	readonly [queryType]: 'subscription';
+};
+
+/**
+ * The return value from a `graphql({query})` call when `query` is a subscription.
+ *
+ * ```ts
+ * //               |-- You are here
+ * //               v
+ * const subResult: GraphqlSubscriptionResult<T> = client.graphql({
+ * 	query: onCreateWidget
+ * });
+ *
+ * const sub = subResult.subscribe({
+ * 	//
+ * 	//            |-- You are here
+ * 	//            v
+ * 	next(message: GraphqlSubscriptionMessage<OnCreateWidgetSubscription>) {
+ * 		handle(message.value);  // <-- type OnCreateWidgetSubscription
+ * 	}
+ * })
+ * ```
+ */
+export type GraphqlSubscriptionResult<T> = Observable<
+	GraphqlSubscriptionMessage<T>
+>;
+
+/**
+ * The shape of messages passed to `next()` from a graphql subscription. E.g.,
+ *
+ * ```ts
+ * const sub = client.graphql({
+ * 	query: onCreateWidget,
+ * }).subscribe({
+ * 	//
+ * 	//            |-- You are here
+ * 	//            v
+ * 	next(message: GraphqlSubscriptionMessage<OnCreateWidgetSubscription>) {
+ * 		handle(message.value);  // <-- type OnCreateWidgetSubscription
+ * 	}
+ * })
+ * ```
+ */
+export type GraphqlSubscriptionMessage<T> = {
+	provider: AWSAppSyncRealTimeProvider;
+	value: { data?: T };
+};
+
 export enum GraphQLAuthError {
 	NO_API_KEY = 'No api-key configured',
 	NO_CURRENT_USER = 'No current user',
@@ -38,3 +95,156 @@ export enum GraphQLAuthError {
  * @see: https://graphql.org/graphql-js/language/#parse
  */
 export type GraphQLOperation = Source | string;
+
+/**
+ * API V6 `graphql({options})` type that can leverage branded graphql `query`
+ * objects and fallback types.
+ */
+export interface GraphQLOptionsV6<
+	FALLBACK_TYPES = unknown,
+	TYPED_GQL_STRING extends string = string
+> {
+	query: TYPED_GQL_STRING | DocumentNode;
+	variables?: GraphQLVariablesV6<FALLBACK_TYPES, TYPED_GQL_STRING>;
+	authMode?: keyof typeof GRAPHQL_AUTH_MODE;
+	authToken?: string;
+	/**
+	 * @deprecated This property should not be used
+	 */
+	userAgentSuffix?: string; // TODO: remove in v6
+}
+
+/**
+ * Result type for `graphql()` operations that don't include any specific
+ * type information. The result could be either a `Promise` or `Subscription`.
+ *
+ * Invoking code should either cast the result or use `?` and `!` operators to
+ * navigate the result objects.
+ */
+export type UnknownGraphQLResponse =
+	| Promise<GraphQLResult<any>>
+	| GraphqlSubscriptionResult<any>;
+
+/**
+ * The expected type for `variables` in a V6 `graphql()` operation with
+ * respect to the given `FALLBACK_TYPES` and `TYPED_GQL_STRING`.
+ */
+export type GraphQLVariablesV6<
+	FALLBACK_TYPES = unknown,
+	TYPED_GQL_STRING extends string = string
+> = TYPED_GQL_STRING extends GeneratedQuery<infer IN, any>
+	? IN
+	: TYPED_GQL_STRING extends GeneratedMutation<infer IN, any>
+	? IN
+	: TYPED_GQL_STRING extends GeneratedSubscription<infer IN, any>
+	? IN
+	: FALLBACK_TYPES extends GraphQLOperationType<infer IN, any>
+	? IN
+	: any;
+
+/**
+ * The expected return type with respect to the given `FALLBACK_TYPE`
+ * and `TYPED_GQL_STRING`.
+ */
+export type GraphQLResponseV6<
+	FALLBACK_TYPE = unknown,
+	TYPED_GQL_STRING extends string = string
+> = TYPED_GQL_STRING extends GeneratedQuery<infer IN, infer QUERY_OUT>
+	? Promise<GraphQLResult<QUERY_OUT>>
+	: TYPED_GQL_STRING extends GeneratedMutation<infer IN, infer MUTATION_OUT>
+	? Promise<GraphQLResult<MUTATION_OUT>>
+	: TYPED_GQL_STRING extends GeneratedSubscription<infer IN, infer SUB_OUT>
+	? GraphqlSubscriptionResult<SUB_OUT>
+	: FALLBACK_TYPE extends GraphQLQuery<infer T>
+	? Promise<GraphQLResult<FALLBACK_TYPE>>
+	: FALLBACK_TYPE extends GraphQLSubscription<infer T>
+	? GraphqlSubscriptionResult<FALLBACK_TYPE>
+	: FALLBACK_TYPE extends GraphQLOperationType<infer IN, infer CUSTOM_OUT>
+	? CUSTOM_OUT
+	: UnknownGraphQLResponse;
+
+/**
+ * The shape customers can use to provide `T` to `graphql<T>()` to specify both
+ * `IN` and `OUT` types (the type of `variables` and the return type, respectively).
+ *
+ * I.E.,
+ *
+ * ```ts
+ * type MyVariablesType = { ... };
+ * type MyResultType = { ... };
+ * type MyOperationType = { variables: MyVariablesType, result: MyResultType };
+ *
+ * const result: MyResultType = graphql<MyOperationType>("graphql string", {
+ * 	variables: {
+ * 		// MyVariablesType
+ * 	}
+ * })
+ * ```
+ */
+export type GraphQLOperationType<IN extends {}, OUT extends {}> = {
+	variables: IN;
+	result: OUT;
+};
+
+/**
+ * Nominal type for branding generated graphql query operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const getWidget = `...` as GeneratedQuery<
+ * 	GetWidgetQueryVariables,
+ * 	GetWidgetQuery
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export type GeneratedQuery<InputType, OutputType> = string & {
+	__generatedQueryInput: InputType;
+	__generatedQueryOutput: OutputType;
+};
+
+/**
+ * Nominal type for branding generated graphql mutation operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const createWidget = `...` as GeneratedQuery<
+ * 	CreateWidgetMutationVariables,
+ * 	CreateWidgetMutation
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export type GeneratedMutation<InputType, OutputType> = string & {
+	__generatedMutationInput: InputType;
+	__generatedMutationOutput: OutputType;
+};
+
+/**
+ * Nominal type for branding generated graphql mutation operation strings with
+ * input and output types.
+ *
+ * E.g.,
+ *
+ * ```ts
+ * export const createWidget = `...` as GeneratedMutation<
+ * 	CreateWidgetMutationVariables,
+ * 	CreateWidgetMutation
+ * >;
+ * ```
+ *
+ * This allows `graphql()` to extract `InputType` and `OutputType` to correctly
+ * assign types to the `variables` and result objects.
+ */
+export type GeneratedSubscription<InputType, OutputType> = string & {
+	__generatedSubscriptionInput: InputType;
+	__generatedSubscriptionOutput: OutputType;
+};