@aws-amplify/api-graphql 3.4.12-api-v6-models.b3abc9b.0 → 4.0.0

package/src/internals/v6.ts

@@ -1,7 +1,12 @@
 // 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';
+import {
+	__amplify,
+	V6Client,
+	GraphQLOptionsV6,
+	GraphQLResponseV6,
+} from '../types';
 
 /**
  * Invokes graphql operations against a graphql service, providing correct input and
@@ -91,6 +96,7 @@ export function graphql<
 	FALLBACK_TYPES = unknown,
 	TYPED_GQL_STRING extends string = string
 >(
+	this: V6Client,
 	options: GraphQLOptionsV6<FALLBACK_TYPES, TYPED_GQL_STRING>,
 	additionalHeaders?: { [key: string]: string }
 ): GraphQLResponseV6<FALLBACK_TYPES, TYPED_GQL_STRING> {
@@ -99,8 +105,34 @@ export function graphql<
 	 * 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);
+	const result = GraphQLAPI.graphql(
+		this[__amplify],
+		options,
+		additionalHeaders
+	);
 	return result as any;
 }
 
+/**
+ * Cancels an inflight request. Only applicable for graphql queries and mutations
+ * @param {any} request - request to cancel
+ * @returns - A boolean indicating if the request was cancelled
+ */
+export function cancel(
+	this: V6Client,
+	promise: Promise<any>,
+	message?: string
+): boolean {
+	return GraphQLAPI.cancel(promise, message);
+}
+
+/**
+ * Checks to see if an error thrown is from an api request cancellation
+ * @param {any} error - Any error
+ * @returns - A boolean indicating if the error was from an api request cancellation
+ */
+export function isCancelError(this: V6Client, error: any): boolean {
+	return GraphQLAPI.isCancelError(error);
+}
+
 export { GraphQLOptionsV6, GraphQLResponseV6 };

package/src/types/PubSub.ts

@@ -0,0 +1,56 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Observer } from 'rxjs';
+export interface SubscriptionObserver<T> {
+	closed: boolean;
+	next(value: T): void;
+	error(errorValue: any): void;
+	complete(): void;
+}
+
+export enum CONTROL_MSG {
+	CONNECTION_CLOSED = 'Connection closed',
+	CONNECTION_FAILED = 'Connection failed',
+	REALTIME_SUBSCRIPTION_INIT_ERROR = 'AppSync Realtime subscription init error',
+	SUBSCRIPTION_ACK = 'Subscription ack',
+	TIMEOUT_DISCONNECT = 'Timeout disconnect',
+}
+
+/** @enum {string} */
+export enum ConnectionState {
+	/*
+	 * The connection is alive and healthy
+	 */
+	Connected = 'Connected',
+	/*
+	 * The connection is alive, but the connection is offline
+	 */
+	ConnectedPendingNetwork = 'ConnectedPendingNetwork',
+	/*
+	 * The connection has been disconnected while in use
+	 */
+	ConnectionDisrupted = 'ConnectionDisrupted',
+	/*
+	 * The connection has been disconnected and the network is offline
+	 */
+	ConnectionDisruptedPendingNetwork = 'ConnectionDisruptedPendingNetwork',
+	/*
+	 * The connection is in the process of connecting
+	 */
+	Connecting = 'Connecting',
+	/*
+	 * The connection is not in use and is being disconnected
+	 */
+	ConnectedPendingDisconnect = 'ConnectedPendingDisconnect',
+	/*
+	 * The connection is not in use and has been disconnected
+	 */
+	Disconnected = 'Disconnected',
+	/*
+	 * The connection is alive, but a keep alive message has been missed
+	 */
+	ConnectedPendingKeepAlive = 'ConnectedPendingKeepAlive',
+}
+
+export type PubSubContent = Record<string, unknown>;
+export type PubSubContentObserver = Observer<PubSubContent>;

package/src/types/index.ts

@@ -1,28 +1,33 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import { AmplifyClassV6, ResourcesConfig } from '@aws-amplify/core';
 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';
+import { Observable } from 'rxjs';
 
+import {
+	GraphQLAuthMode,
+	DocumentType,
+} from '@aws-amplify/core/internals/utils';
+import { AmplifyServer } from '@aws-amplify/core/internals/adapter-core';
+
+export { CONTROL_MSG, ConnectionState } from './PubSub';
 /**
  * Loose/Unknown options for raw GraphQLAPICategory `graphql()`.
  */
 export interface GraphQLOptions {
 	query: string | DocumentNode;
-	variables?: object;
-	authMode?: keyof typeof GRAPHQL_AUTH_MODE;
+	variables?: Record<string, DocumentType>;
+	authMode?: GraphQLAuthMode;
 	authToken?: string;
 	/**
 	 * @deprecated This property should not be used
 	 */
-	userAgentSuffix?: string; // TODO: remove in v6
+	userAgentSuffix?: string;
 }
 
 export interface GraphQLResult<T = object> {
-	data?: T;
+	data: T;
 	errors?: GraphQLError[];
 	extensions?: {
 		[key: string]: any;
@@ -37,6 +42,82 @@ export type GraphQLSubscription<T> = T & {
 	readonly [queryType]: 'subscription';
 };
 
+/**
+ * Accepts a code generated model type and returns a supertype that
+ * can accept return values from the relevant graphql operations.
+ *
+ * For example:
+ *
+ * ```typescript
+ * import { GraphQLReturnType } from 'aws-amplify/api';
+ * import { MyModel } from './API';
+ * import { getMyModel } from './graphql/queries';
+ *
+ * const [item, setItem] = useState<GraphQLReturnType<MyModel>>();
+ * setItem(await client.graphql({ query: getMyModel }).data.getMyModel!)
+ * ```
+ *
+ * Trying to assign the result of a `getMyModel` operation directly to a
+ * `MyModel` variables won't necessarily work, because normally-required related
+ * models might not be part of the selection set.
+ *
+ * This util simply makes related model properties optional recursively.
+ */
+export type GraphQLReturnType<T> = T extends {}
+	? {
+			[K in keyof T]?: GraphQLReturnType<T[K]>;
+	  }
+	: T;
+
+/**
+ * Describes a paged list result from AppSync, which can either
+ * live at the top query or property (e.g., related model) level.
+ */
+type PagedList<T, TYPENAME> = {
+	__typename: TYPENAME;
+	nextToken?: string | null | undefined;
+	items: Array<T>;
+};
+
+/**
+ * Recursively looks through a result type and removes nulls and
+ * and undefined from `PagedList` types.
+ *
+ * Although a graphql response might contain empty values in an
+ * array, this will only be the case when we also have errors,
+ * which will then be *thrown*.
+ */
+type WithListsFixed<T> = T extends PagedList<infer IT, infer NAME>
+	? PagedList<Exclude<IT, null | undefined>, NAME>
+	: T extends {}
+	? {
+			[K in keyof T]: WithListsFixed<T[K]>;
+	  }
+	: T;
+
+/**
+ * Returns an updated response type to always return a value.
+ */
+type NeverEmpty<T> = {
+	[K in keyof T]-?: Exclude<WithListsFixed<T[K]>, undefined | null>;
+};
+
+/**
+ * Replaces all list result types in a query result with types to exclude
+ * nulls and undefined from list member unions.
+ *
+ * If empty members are present, there will also be errors present,
+ * and the response will instead be *thrown*.
+ */
+type FixedQueryResult<T> = Exclude<
+	T[keyof T],
+	null | undefined
+> extends PagedList<any, any>
+	? {
+			[K in keyof T]-?: WithListsFixed<Exclude<T[K], null | undefined>>;
+	  }
+	: T;
+
 /**
  * The return value from a `graphql({query})` call when `query` is a subscription.
  *
@@ -78,8 +159,24 @@ export type GraphqlSubscriptionResult<T> = Observable<
  * ```
  */
 export type GraphqlSubscriptionMessage<T> = {
-	provider: AWSAppSyncRealTimeProvider;
-	value: { data?: T };
+	data: T;
+};
+
+export interface AWSAppSyncRealTimeProviderOptions {
+	appSyncGraphqlEndpoint?: string;
+	authenticationType?: GraphQLAuthMode;
+	query?: string;
+	variables?: Record<string, unknown>;
+	apiKey?: string;
+	region?: string;
+	graphql_headers?: () => {} | (() => Promise<{}>);
+	additionalHeaders?: { [key: string]: string };
+}
+
+export type AWSAppSyncRealTimeProvider = {
+	subscribe(
+		options?: AWSAppSyncRealTimeProviderOptions
+	): Observable<Record<string, unknown>>;
 };
 
 export enum GraphQLAuthError {
@@ -106,12 +203,12 @@ export interface GraphQLOptionsV6<
 > {
 	query: TYPED_GQL_STRING | DocumentNode;
 	variables?: GraphQLVariablesV6<FALLBACK_TYPES, TYPED_GQL_STRING>;
-	authMode?: keyof typeof GRAPHQL_AUTH_MODE;
+	authMode?: GraphQLAuthMode;
 	authToken?: string;
 	/**
 	 * @deprecated This property should not be used
 	 */
-	userAgentSuffix?: string; // TODO: remove in v6
+	userAgentSuffix?: string;
 }
 
 /**
@@ -150,11 +247,11 @@ 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>>
+	? Promise<GraphQLResult<FixedQueryResult<QUERY_OUT>>>
 	: TYPED_GQL_STRING extends GeneratedMutation<infer IN, infer MUTATION_OUT>
-	? Promise<GraphQLResult<MUTATION_OUT>>
+	? Promise<GraphQLResult<NeverEmpty<MUTATION_OUT>>>
 	: TYPED_GQL_STRING extends GeneratedSubscription<infer IN, infer SUB_OUT>
-	? GraphqlSubscriptionResult<SUB_OUT>
+	? GraphqlSubscriptionResult<NeverEmpty<SUB_OUT>>
 	: FALLBACK_TYPE extends GraphQLQuery<infer T>
 	? Promise<GraphQLResult<FALLBACK_TYPE>>
 	: FALLBACK_TYPE extends GraphQLSubscription<infer T>
@@ -248,3 +345,66 @@ export type GeneratedSubscription<InputType, OutputType> = string & {
 	__generatedSubscriptionInput: InputType;
 	__generatedSubscriptionOutput: OutputType;
 };
+
+type FilteredKeys<T> = {
+	[P in keyof T]: T[P] extends never ? never : P;
+}[keyof T];
+type ExcludeNeverFields<O> = {
+	[K in FilteredKeys<O>]: O[K];
+};
+
+export const __amplify = Symbol('amplify');
+
+export type V6Client<T extends Record<any, any> = never> = ExcludeNeverFields<{
+	[__amplify]: AmplifyClassV6;
+	graphql: GraphQLMethod;
+	cancel: (promise: Promise<any>, message?: string) => boolean;
+	isCancelError: (error: any) => boolean;
+}>;
+
+export type V6ClientSSR<T extends Record<any, any> = never> =
+	ExcludeNeverFields<{
+		[__amplify]: AmplifyClassV6;
+		graphql: GraphQLMethodSSR;
+		cancel: (promise: Promise<any>, message?: string) => boolean;
+		isCancelError: (error: any) => boolean;
+	}>;
+
+export type GraphQLMethod = <
+	FALLBACK_TYPES = unknown,
+	TYPED_GQL_STRING extends string = string
+>(
+	options: GraphQLOptionsV6<FALLBACK_TYPES, TYPED_GQL_STRING>,
+	additionalHeaders?:
+		| {
+				[key: string]: string;
+		  }
+		| undefined
+) => GraphQLResponseV6<FALLBACK_TYPES, TYPED_GQL_STRING>;
+
+export type GraphQLMethodSSR = <
+	FALLBACK_TYPES = unknown,
+	TYPED_GQL_STRING extends string = string
+>(
+	contextSpec: AmplifyServer.ContextSpec,
+	options: GraphQLOptionsV6<FALLBACK_TYPES, TYPED_GQL_STRING>,
+	additionalHeaders?:
+		| {
+				[key: string]: string;
+		  }
+		| undefined
+) => GraphQLResponseV6<FALLBACK_TYPES, TYPED_GQL_STRING>;
+
+/**
+ * @private
+ *
+ * The knobs available for configuring `server/generateClient` internally.
+ */
+export type ServerClientGenerationParams = {
+	amplify:
+		| null // null expected when used with `generateServerClient`
+		// closure expected with `generateServerClientUsingCookies`
+		| ((fn: (amplify: any) => Promise<any>) => Promise<AmplifyClassV6>);
+	// global env-sourced config use for retrieving modelIntro
+	config: ResourcesConfig;
+};

package/src/utils/ConnectionStateMonitor.ts

@@ -0,0 +1,199 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Observable, Observer, SubscriptionLike, map, filter } from 'rxjs';
+import { ConnectionState } from '../types/PubSub';
+import { ReachabilityMonitor } from './ReachabilityMonitor';
+
+// Internal types for tracking different connection states
+type LinkedConnectionState = 'connected' | 'disconnected';
+type LinkedHealthState = 'healthy' | 'unhealthy';
+type LinkedConnectionStates = {
+	networkState: LinkedConnectionState;
+	connectionState: LinkedConnectionState | 'connecting';
+	intendedConnectionState: LinkedConnectionState;
+	keepAliveState: LinkedHealthState;
+};
+
+export const CONNECTION_CHANGE: {
+	[key in
+		| 'KEEP_ALIVE_MISSED'
+		| 'KEEP_ALIVE'
+		| 'CONNECTION_ESTABLISHED'
+		| 'CONNECTION_FAILED'
+		| 'CLOSING_CONNECTION'
+		| 'OPENING_CONNECTION'
+		| 'CLOSED'
+		| 'ONLINE'
+		| 'OFFLINE']: Partial<LinkedConnectionStates>;
+} = {
+	KEEP_ALIVE_MISSED: { keepAliveState: 'unhealthy' },
+	KEEP_ALIVE: { keepAliveState: 'healthy' },
+	CONNECTION_ESTABLISHED: { connectionState: 'connected' },
+	CONNECTION_FAILED: {
+		intendedConnectionState: 'disconnected',
+		connectionState: 'disconnected',
+	},
+	CLOSING_CONNECTION: { intendedConnectionState: 'disconnected' },
+	OPENING_CONNECTION: {
+		intendedConnectionState: 'connected',
+		connectionState: 'connecting',
+	},
+	CLOSED: { connectionState: 'disconnected' },
+	ONLINE: { networkState: 'connected' },
+	OFFLINE: { networkState: 'disconnected' },
+};
+
+export class ConnectionStateMonitor {
+	/**
+	 * @private
+	 */
+	private _linkedConnectionState: LinkedConnectionStates;
+	private _linkedConnectionStateObservable: Observable<LinkedConnectionStates>;
+	private _linkedConnectionStateObserver: Observer<LinkedConnectionStates>;
+	private _networkMonitoringSubscription?: SubscriptionLike;
+	private _initialNetworkStateSubscription?: SubscriptionLike;
+
+	constructor() {
+		this._networkMonitoringSubscription = undefined;
+		this._linkedConnectionState = {
+			networkState: 'connected',
+			connectionState: 'disconnected',
+			intendedConnectionState: 'disconnected',
+			keepAliveState: 'healthy',
+		};
+
+		// Attempt to update the state with the current actual network state
+		this._initialNetworkStateSubscription = ReachabilityMonitor().subscribe(
+			({ online }) => {
+				this.record(
+					online ? CONNECTION_CHANGE.ONLINE : CONNECTION_CHANGE.OFFLINE
+				);
+				this._initialNetworkStateSubscription?.unsubscribe();
+			}
+		);
+
+		this._linkedConnectionStateObservable =
+			new Observable<LinkedConnectionStates>(connectionStateObserver => {
+				connectionStateObserver.next(this._linkedConnectionState);
+				this._linkedConnectionStateObserver = connectionStateObserver;
+			});
+	}
+
+	/**
+	 * Turn network state monitoring on if it isn't on already
+	 */
+	private enableNetworkMonitoring() {
+		// If no initial network state was discovered, stop trying
+		this._initialNetworkStateSubscription?.unsubscribe();
+
+		// Maintain the network state based on the reachability monitor
+		if (this._networkMonitoringSubscription === undefined) {
+			this._networkMonitoringSubscription = ReachabilityMonitor().subscribe(
+				({ online }) => {
+					this.record(
+						online ? CONNECTION_CHANGE.ONLINE : CONNECTION_CHANGE.OFFLINE
+					);
+				}
+			);
+		}
+	}
+
+	/**
+	 * Turn network state monitoring off if it isn't off already
+	 */
+	private disableNetworkMonitoring() {
+		this._networkMonitoringSubscription?.unsubscribe();
+		this._networkMonitoringSubscription = undefined;
+	}
+
+	/**
+	 * Get the observable that allows us to monitor the connection state
+	 *
+	 * @returns {Observable<ConnectionState>} - The observable that emits ConnectionState updates
+	 */
+	public get connectionStateObservable(): Observable<ConnectionState> {
+		let previous: ConnectionState;
+
+		// The linked state aggregates state changes to any of the network, connection,
+		// intendedConnection and keepAliveHealth. Some states will change these independent
+		// states without changing the overall connection state.
+
+		// After translating from linked states to ConnectionState, then remove any duplicates
+		return this._linkedConnectionStateObservable
+			.pipe(
+				map(value => {
+					return this.connectionStatesTranslator(value);
+				})
+			)
+			.pipe(
+				filter(current => {
+					const toInclude = current !== previous;
+					previous = current;
+					return toInclude;
+				})
+			);
+	}
+
+	/*
+	 * Updates local connection state and emits the full state to the observer.
+	 */
+	record(statusUpdates: Partial<LinkedConnectionStates>) {
+		// Maintain the network monitor
+		if (statusUpdates.intendedConnectionState === 'connected') {
+			this.enableNetworkMonitoring();
+		} else if (statusUpdates.intendedConnectionState === 'disconnected') {
+			this.disableNetworkMonitoring();
+		}
+
+		// Maintain the socket state
+		const newSocketStatus = {
+			...this._linkedConnectionState,
+			...statusUpdates,
+		};
+
+		this._linkedConnectionState = { ...newSocketStatus };
+
+		this._linkedConnectionStateObserver?.next(this._linkedConnectionState);
+	}
+
+	/*
+	 * Translate the ConnectionState structure into a specific ConnectionState string literal union
+	 */
+	private connectionStatesTranslator({
+		connectionState,
+		networkState,
+		intendedConnectionState,
+		keepAliveState,
+	}: LinkedConnectionStates): ConnectionState {
+		if (connectionState === 'connected' && networkState === 'disconnected')
+			return ConnectionState.ConnectedPendingNetwork;
+
+		if (
+			connectionState === 'connected' &&
+			intendedConnectionState === 'disconnected'
+		)
+			return ConnectionState.ConnectedPendingDisconnect;
+
+		if (
+			connectionState === 'disconnected' &&
+			intendedConnectionState === 'connected' &&
+			networkState === 'disconnected'
+		)
+			return ConnectionState.ConnectionDisruptedPendingNetwork;
+
+		if (
+			connectionState === 'disconnected' &&
+			intendedConnectionState === 'connected'
+		)
+			return ConnectionState.ConnectionDisrupted;
+
+		if (connectionState === 'connected' && keepAliveState === 'unhealthy')
+			return ConnectionState.ConnectedPendingKeepAlive;
+
+		// All remaining states directly correspond to the connection state
+		if (connectionState === 'connecting') return ConnectionState.Connecting;
+		if (connectionState === 'disconnected') return ConnectionState.Disconnected;
+		return ConnectionState.Connected;
+	}
+}

package/src/utils/ReachabilityMonitor/index.native.ts

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Reachability } from '@aws-amplify/core/internals/utils';
+import { default as NetInfo } from '@react-native-community/netinfo';
+
+export const ReachabilityMonitor = () =>
+	new Reachability().networkMonitor(NetInfo);

package/src/utils/ReachabilityMonitor/index.ts

@@ -0,0 +1,4 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Reachability } from '@aws-amplify/core/internals/utils';
+export const ReachabilityMonitor = () => new Reachability().networkMonitor();

package/src/utils/ReconnectionMonitor.ts

@@ -0,0 +1,76 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Observer } from 'rxjs';
+import { RECONNECT_DELAY, RECONNECT_INTERVAL } from '../Providers/constants';
+
+export enum ReconnectEvent {
+	START_RECONNECT = 'START_RECONNECT',
+	HALT_RECONNECT = 'HALT_RECONNECT',
+}
+
+/**
+ * Captures the reconnect event logic used to determine when to reconnect to PubSub providers.
+ *   Reconnnect attempts are delayed by 5 seconds to let the interface settle.
+ *   Attempting to reconnect only once creates unrecoverable states when the network state isn't
+ *   supported by the browser, so this keeps retrying every minute until halted.
+ */
+export class ReconnectionMonitor {
+	private reconnectObservers: Observer<void>[] = [];
+	private reconnectIntervalId?: ReturnType<typeof setInterval>;
+	private reconnectSetTimeoutId?: ReturnType<typeof setTimeout>;
+
+	/**
+	 * Add reconnect observer to the list of observers to alert on reconnect
+	 */
+	addObserver(reconnectObserver: Observer<void>) {
+		this.reconnectObservers.push(reconnectObserver);
+	}
+
+	/**
+	 * Given a reconnect event, start the appropriate behavior
+	 */
+	record(event: ReconnectEvent) {
+		if (event === ReconnectEvent.START_RECONNECT) {
+			// If the reconnection hasn't been started
+			if (
+				this.reconnectSetTimeoutId === undefined &&
+				this.reconnectIntervalId === undefined
+			) {
+				this.reconnectSetTimeoutId = setTimeout(() => {
+					// Reconnect now
+					this._triggerReconnect();
+					// Retry reconnect every periodically until it works
+					this.reconnectIntervalId = setInterval(() => {
+						this._triggerReconnect();
+					}, RECONNECT_INTERVAL);
+				}, RECONNECT_DELAY);
+			}
+		}
+
+		if (event === ReconnectEvent.HALT_RECONNECT) {
+			if (this.reconnectIntervalId) {
+				clearInterval(this.reconnectIntervalId);
+				this.reconnectIntervalId = undefined;
+			}
+			if (this.reconnectSetTimeoutId) {
+				clearTimeout(this.reconnectSetTimeoutId);
+				this.reconnectSetTimeoutId = undefined;
+			}
+		}
+	}
+
+	/**
+	 * Complete all reconnect observers
+	 */
+	close() {
+		this.reconnectObservers.forEach(reconnectObserver => {
+			reconnectObserver.complete?.();
+		});
+	}
+
+	private _triggerReconnect() {
+		this.reconnectObservers.forEach(reconnectObserver => {
+			reconnectObserver.next?.();
+		});
+	}
+}

package/src/utils/errors/APIError.ts

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	AmplifyError,
+	AmplifyErrorParams,
+} from '@aws-amplify/core/internals/utils';
+
+/**
+ * @internal
+ */
+export class APIError extends AmplifyError {
+	constructor(params: AmplifyErrorParams) {
+		super(params);
+
+		// Hack for making the custom error class work when transpiled to es5
+		// TODO: Delete the following 2 lines after we change the build target to >= es2015
+		this.constructor = APIError;
+		Object.setPrototypeOf(this, APIError.prototype);
+	}
+}

package/src/utils/errors/assertValidationError.ts

@@ -0,0 +1,19 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { APIError } from './APIError';
+import { APIValidationErrorCode, validationErrorMap } from './validation';
+
+/**
+ * @internal
+ */
+export function assertValidationError(
+	assertion: boolean,
+	name: APIValidationErrorCode
+): asserts assertion {
+	const { message, recoverySuggestion } = validationErrorMap[name];
+
+	if (!assertion) {
+		throw new APIError({ name, message, recoverySuggestion });
+	}
+}