@aws-amplify/datastore 3.7.3 → 3.7.4-custom-pk.86

package/src/types.ts

@@ -10,9 +10,13 @@ import {
 	isAWSURL,
 	isAWSPhone,
 	isAWSIPAddress,
+	extractPrimaryKeyFieldNames,
 } from './util';
 import { PredicateAll } from './predicates';
 import { GRAPHQL_AUTH_MODE } from '@aws-amplify/api-graphql';
+import { Auth } from '@aws-amplify/auth';
+import { API } from '@aws-amplify/api';
+import Cache from '@aws-amplify/cache';
 import { Adapter } from './storage/adapter';
 
 //#region Schema types
@@ -60,25 +64,29 @@ type SchemaEnum = {
 export type ModelAssociation = AssociatedWith | TargetNameAssociation;
 type AssociatedWith = {
 	connectionType: 'HAS_MANY' | 'HAS_ONE';
-	associatedWith: string;
+	associatedWith: string | string[];
 	targetName?: string;
+	targetNames?: string[];
 };
+
 export function isAssociatedWith(obj: any): obj is AssociatedWith {
 	return obj && obj.associatedWith;
 }
 
 type TargetNameAssociation = {
 	connectionType: 'BELONGS_TO';
-	targetName: string;
+	targetName?: string;
+	targetNames?: string[];
 };
+
 export function isTargetNameAssociation(
 	obj: any
 ): obj is TargetNameAssociation {
-	return obj && obj.targetName;
+	return obj?.targetName || obj?.targetNames;
 }
 
 export type ModelAttributes = ModelAttribute[];
-type ModelAttribute = { type: string; properties?: Record<string, any> };
+export type ModelAttribute = { type: string; properties?: Record<string, any> };
 
 export type ModelAuthRule = {
 	allow: string;
@@ -120,6 +128,7 @@ type ModelAttributeKey = {
 type ModelAttributePrimaryKey = {
 	type: 'key';
 	properties: {
+		name: never;
 		fields: string[];
 	};
 };
@@ -333,33 +342,134 @@ export type NonModelTypeConstructor<T> = {
 };
 
 // Class for model
-export type PersistentModelConstructor<
-	T extends PersistentModel,
-	K extends PersistentModelMetaData = {
-		readOnlyFields: 'createdAt' | 'updatedAt';
-	}
-> = {
-	new (init: ModelInit<T, K>): T;
-	copyOf(src: T, mutator: (draft: MutableModel<T, K>) => void): T;
+export type PersistentModelConstructor<T extends PersistentModel> = {
+	new (init: ModelInit<T, PersistentModelMetaData<T>>): T;
+	copyOf(
+		src: T,
+		mutator: (draft: MutableModel<T, PersistentModelMetaData<T>>) => void
+	): T;
 };
 
 export type TypeConstructorMap = Record<
 	string,
-	PersistentModelConstructor<any> | NonModelTypeConstructor<any>
+	PersistentModelConstructor<any> | NonModelTypeConstructor<unknown>
+>;
+
+export declare const __identifierBrand__: unique symbol;
+export type IdentifierBrand<T, K> = T & { [__identifierBrand__]: K };
+
+// datastore generates a uuid for you
+export type ManagedIdentifier<T, F extends keyof T> = IdentifierBrand<
+	{ field: F extends string ? F : never; type: T },
+	'ManagedIdentifier'
+>;
+
+// you can provide a value, if not, datastore generates a uuid for you
+export type OptionallyManagedIdentifier<T, F extends keyof T> = IdentifierBrand<
+	{ field: F extends string ? F : never; type: T },
+	'OptionallyManagedIdentifier'
+>;
+
+// You provide the values
+export type CompositeIdentifier<T, K extends Array<keyof T>> = IdentifierBrand<
+	{ fields: K; type: T },
+	'CompositeIdentifier'
 >;
 
+// You provide the value
+export type CustomIdentifier<T, K extends keyof T> = CompositeIdentifier<
+	T,
+	[K]
+>;
+
+export type Identifier<T> =
+	| ManagedIdentifier<T, any>
+	| OptionallyManagedIdentifier<T, any>
+	| CompositeIdentifier<T, any>
+	| CustomIdentifier<T, any>;
+
+export type IdentifierFields<
+	T extends PersistentModel,
+	M extends PersistentModelMetaData<T> = never
+> = (MetadataOrDefault<T, M>['identifier'] extends
+	| ManagedIdentifier<any, any>
+	| OptionallyManagedIdentifier<any, any>
+	? MetadataOrDefault<T, M>['identifier']['field']
+	: MetadataOrDefault<T, M>['identifier'] extends CompositeIdentifier<
+			T,
+			infer B
+	  >
+	? B[number] // B[number]
+	: MetadataOrDefault<T, M>['identifier']['field']) &
+	string;
+
+export type IdentifierFieldsForInit<
+	T extends PersistentModel,
+	M extends PersistentModelMetaData<T>
+> = MetadataOrDefault<T, M>['identifier'] extends
+	| DefaultPersistentModelMetaData
+	| ManagedIdentifier<T, any>
+	? never
+	: MetadataOrDefault<T, M>['identifier'] extends OptionallyManagedIdentifier<
+			T,
+			any
+	  >
+	? IdentifierFields<T, M>
+	: MetadataOrDefault<T, M>['identifier'] extends CompositeIdentifier<T, any>
+	? IdentifierFields<T, M>
+	: never;
+
 // Instance of model
-export type PersistentModelMetaData = {
-	readOnlyFields: string;
+export declare const __modelMeta__: unique symbol;
+
+export type PersistentModelMetaData<T> = {
+	identifier?: Identifier<T>;
+	readOnlyFields?: string;
+};
+
+export type DefaultPersistentModelMetaData = {
+	identifier: ManagedIdentifier<{ id: string }, 'id'>;
+	readOnlyFields: never;
 };
 
-export type PersistentModel = Readonly<{ id: string } & Record<string, any>>;
+export type MetadataOrDefault<
+	T extends PersistentModel,
+	_ extends PersistentModelMetaData<T> = never
+> = T extends {
+	[__modelMeta__]: PersistentModelMetaData<T>;
+}
+	? T[typeof __modelMeta__]
+	: DefaultPersistentModelMetaData;
+
+export type PersistentModel = Readonly<Record<string, any>>;
+
+export type MetadataReadOnlyFields<
+	T extends PersistentModel,
+	M extends PersistentModelMetaData<T>
+> = Extract<
+	MetadataOrDefault<T, M>['readOnlyFields'] | M['readOnlyFields'],
+	keyof T
+>;
+
+// This type omits the metadata field in the constructor init object
+// This type omits identifier fields in the constructor init object
+// This type omits readOnlyFields in the constructor init object
+// This type requires some identifiers in the constructor init object (e.g. CustomIdentifier)
+// This type makes optional some identifiers in the constructor init object (e.g. OptionallyManagedIdentifier)
 export type ModelInit<
+	T extends PersistentModel,
+	M extends PersistentModelMetaData<T> = {}
+> = Omit<
 	T,
-	K extends PersistentModelMetaData = {
-		readOnlyFields: 'createdAt' | 'updatedAt';
-	}
-> = Omit<T, 'id' | K['readOnlyFields']>;
+	typeof __modelMeta__ | IdentifierFields<T, M> | MetadataReadOnlyFields<T, M>
+> &
+	(MetadataOrDefault<T, M>['identifier'] extends OptionallyManagedIdentifier<
+		T,
+		any
+	>
+		? Partial<Pick<T, IdentifierFieldsForInit<T, M>>>
+		: Required<Pick<T, IdentifierFieldsForInit<T, M>>>);
+
 type DeepWritable<T> = {
 	-readonly [P in keyof T]: T[P] extends TypeName<T[P]>
 		? T[P]
@@ -367,22 +477,76 @@ type DeepWritable<T> = {
 };
 
 export type MutableModel<
-	T extends Record<string, any>,
-	K extends PersistentModelMetaData = {
-		readOnlyFields: 'createdAt' | 'updatedAt';
-	}
+	T extends PersistentModel,
+	M extends PersistentModelMetaData<T> = {}
 	// This provides Intellisense with ALL of the properties, regardless of read-only
 	// but will throw a linting error if trying to overwrite a read-only property
-> = DeepWritable<Omit<T, 'id' | K['readOnlyFields']>> &
-	Readonly<Pick<T, 'id' | K['readOnlyFields']>>;
+> = DeepWritable<
+	Omit<T, IdentifierFields<T, M> | MetadataReadOnlyFields<T, M>>
+> &
+	Readonly<Pick<T, IdentifierFields<T, M> | MetadataReadOnlyFields<T, M>>>;
 
 export type ModelInstanceMetadata = {
-	id: string;
 	_version: number;
 	_lastChangedAt: number;
 	_deleted: boolean;
 };
 
+export type IdentifierFieldValue<
+	T extends PersistentModel,
+	M extends PersistentModelMetaData<T>
+> = MetadataOrDefault<T, M>['identifier'] extends CompositeIdentifier<T, any>
+	? MetadataOrDefault<T, M>['identifier']['fields'] extends [any]
+		? T[MetadataOrDefault<T, M>['identifier']['fields'][0]]
+		: never
+	: T[MetadataOrDefault<T, M>['identifier']['field']];
+
+export type IdentifierFieldOrIdentifierObject<
+	T extends PersistentModel,
+	M extends PersistentModelMetaData<T>
+> = Pick<T, IdentifierFields<T, M>> | IdentifierFieldValue<T, M>;
+
+export function isIdentifierFieldValue<T extends PersistentModel>(
+	obj: any,
+	modelDefinition: SchemaModel
+): obj is IdentifierFieldValue<T extends PersistentModel ? T : never, any> {
+	const keys = extractPrimaryKeyFieldNames(modelDefinition);
+
+	if (keys.length === 1) {
+		const { type } = modelDefinition?.fields[keys[0]] ?? {};
+
+		if (isGraphQLScalarType(type)) {
+			const jsType = GraphQLScalarType.getJSType(type);
+
+			return typeof obj === jsType;
+		}
+
+		return false;
+	}
+
+	return false;
+}
+
+export function isIdentifierFieldOrObject<T extends PersistentModel>(
+	obj: any,
+	modelDefinition: SchemaModel
+): obj is IdentifierFieldOrIdentifierObject<T, any> {
+	return (
+		isIdentifierFieldValue<T>(obj, modelDefinition) ||
+		isIdentifierObject<T>(obj, modelDefinition)
+	);
+}
+
+export function isIdentifierObject<T extends PersistentModel>(
+	obj: any,
+	modelDefinition: SchemaModel
+): obj is IdentifierFields<T extends PersistentModel ? T : never, any> {
+	const keys = extractPrimaryKeyFieldNames(modelDefinition);
+
+	return (
+		typeof obj === 'object' && obj && keys.every(k => obj[k] !== undefined)
+	);
+}
 //#endregion
 
 //#region Subscription messages
@@ -392,11 +556,17 @@ export enum OpType {
 	DELETE = 'DELETE',
 }
 
-export type SubscriptionMessage<T extends PersistentModel> = {
+export type SubscriptionMessage<T extends PersistentModel> = Pick<
+	InternalSubscriptionMessage<T>,
+	'opType' | 'element' | 'model' | 'condition'
+>;
+
+export type InternalSubscriptionMessage<T extends PersistentModel> = {
 	opType: OpType;
 	element: T;
 	model: PersistentModelConstructor<T>;
 	condition: PredicatesGroup<T> | null;
+	savedElement?: T;
 };
 
 export type DataStoreSnapshot<T extends PersistentModel> = {
@@ -407,15 +577,14 @@ export type DataStoreSnapshot<T extends PersistentModel> = {
 
 //#region Predicates
 
-export type PredicateExpression<M extends PersistentModel, FT> = TypeName<
+export type PredicateExpression<
+	M extends PersistentModel,
 	FT
-> extends keyof MapTypeToOperands<FT>
+> = TypeName<FT> extends keyof MapTypeToOperands<FT>
 	? (
 			operator: keyof MapTypeToOperands<FT>[TypeName<FT>],
 			// make the operand type match the type they're trying to filter on
-			operand: MapTypeToOperands<FT>[TypeName<FT>][keyof MapTypeToOperands<
-				FT
-			>[TypeName<FT>]]
+			operand: MapTypeToOperands<FT>[TypeName<FT>][keyof MapTypeToOperands<FT>[TypeName<FT>]]
 	  ) => ModelPredicate<M>
 	: never;
 
@@ -483,8 +652,7 @@ export type PredicateGroups<T extends PersistentModel> = {
 
 export type ModelPredicate<M extends PersistentModel> = {
 	[K in keyof M]-?: PredicateExpression<M, NonNullable<M[K]>>;
-} &
-	PredicateGroups<M>;
+} & PredicateGroups<M>;
 
 export type ProducerModelPredicate<M extends PersistentModel> = (
 	condition: ModelPredicate<M>
@@ -574,9 +742,10 @@ export type SortPredicate<T extends PersistentModel> = {
 	[K in keyof T]-?: SortPredicateExpression<T, NonNullable<T[K]>>;
 };
 
-export type SortPredicateExpression<M extends PersistentModel, FT> = TypeName<
+export type SortPredicateExpression<
+	M extends PersistentModel,
 	FT
-> extends keyof MapTypeToOperands<FT>
+> = TypeName<FT> extends keyof MapTypeToOperands<FT>
 	? (sortDirection: keyof typeof SortDirection) => SortPredicate<M>
 	: never;
 
@@ -585,9 +754,8 @@ export enum SortDirection {
 	DESCENDING = 'DESCENDING',
 }
 
-export type SortPredicatesGroup<
-	T extends PersistentModel
-> = SortPredicateObject<T>[];
+export type SortPredicatesGroup<T extends PersistentModel> =
+	SortPredicateObject<T>[];
 
 export type SortPredicateObject<T extends PersistentModel> = {
 	field: keyof T;
@@ -628,11 +796,21 @@ export type RelationType = {
 	modelName: string;
 	relationType: 'HAS_ONE' | 'HAS_MANY' | 'BELONGS_TO';
 	targetName?: string;
-	associatedWith?: string;
+	targetNames?: string[];
+	associatedWith?: string | string[];
+};
+
+type IndexOptions = {
+	unique?: boolean;
 };
 
+export type IndexesType = Array<[string, string[], IndexOptions?]>;
+
 export type RelationshipType = {
-	[modelName: string]: { indexes: string[]; relationTypes: RelationType[] };
+	[modelName: string]: {
+		indexes: IndexesType;
+		relationTypes: RelationType[];
+	};
 };
 
 //#endregion
@@ -654,7 +832,7 @@ export type DataStoreConfig = {
 	DataStore?: {
 		authModeStrategyType?: AuthModeStrategyType;
 		conflictHandler?: ConflictHandler; // default : retry until client wins up to x times
-		errorHandler?: (error: SyncError) => void; // default : logger.warn
+		errorHandler?: (error: SyncError<PersistentModel>) => void; // default : logger.warn
 		maxRecordsToSync?: number; // merge
 		syncPageSize?: number;
 		fullSyncInterval?: number;
@@ -664,7 +842,7 @@ export type DataStoreConfig = {
 	};
 	authModeStrategyType?: AuthModeStrategyType;
 	conflictHandler?: ConflictHandler; // default : retry until client wins up to x times
-	errorHandler?: (error: SyncError) => void; // default : logger.warn
+	errorHandler?: (error: SyncError<PersistentModel>) => void; // default : logger.warn
 	maxRecordsToSync?: number; // merge
 	syncPageSize?: number;
 	fullSyncInterval?: number;
@@ -771,15 +949,33 @@ export type SyncConflict = {
 	attempts: number;
 };
 
-export type SyncError = {
+export type SyncError<T extends PersistentModel> = {
 	message: string;
-	errorType: string;
-	errorInfo: string;
-	localModel: PersistentModel;
-	remoteModel: PersistentModel;
+	errorType: ErrorType;
+	errorInfo?: string;
+	recoverySuggestion?: string;
+	model?: string;
+	localModel: T;
+	remoteModel: T;
+	process: ProcessName;
 	operation: string;
+	cause?: Error;
 };
 
+export type ErrorType =
+	| 'ConfigError'
+	| 'BadModel'
+	| 'BadRecord'
+	| 'Unauthorized'
+	| 'Transient'
+	| 'Unknown';
+
+export enum ProcessName {
+	'sync' = 'sync',
+	'mutate' = 'mutate',
+	'subscribe' = 'subscribe',
+}
+
 export const DISCARD = Symbol('DISCARD');
 
 export type ConflictHandler = (
@@ -788,7 +984,7 @@ export type ConflictHandler = (
 	| Promise<PersistentModel | typeof DISCARD>
 	| PersistentModel
 	| typeof DISCARD;
-export type ErrorHandler = (error: SyncError) => void;
+export type ErrorHandler = (error: SyncError<PersistentModel>) => void;
 
 export type DeferredCallbackResolverOptions = {
 	callback: () => void;
@@ -801,3 +997,9 @@ export enum LimitTimerRaceResolvedValues {
 	TIMER = 'TIMER',
 }
 //#endregion
+
+export type AmplifyContext = {
+	Auth: typeof Auth;
+	API: typeof API;
+	Cache: typeof Cache;
+};