@aws-amplify/data-schema 0.15.0 → 0.16.0

package/src/ModelType.ts

@@ -0,0 +1,345 @@
+import type {
+  SetTypeSubArg,
+  SecondaryIndexIrShape,
+} from '@aws-amplify/data-schema-types';
+import { Brand, brand } from './util';
+import { ModelField, InternalField } from './ModelField';
+import type {
+  ModelRelationalField,
+  InternalRelationalField,
+  ModelRelationalFieldParamShape,
+} from './ModelRelationalField';
+import { AllowModifier, Authorization, allow } from './Authorization';
+import { RefType } from './RefType';
+import { EnumType, EnumTypeParamShape } from './EnumType';
+import { CustomType, CustomTypeParamShape } from './CustomType';
+import {
+  ModelIndexType,
+  InternalModelIndexType,
+  modelIndex,
+} from './ModelIndex';
+import { SecondaryIndexToIR } from './MappedTypes/MapSecondaryIndexes';
+
+const brandName = 'modelType';
+
+type ModelFields = Record<
+  string,
+  | ModelField<any, any, any>
+  | ModelRelationalField<any, string, any, any>
+  | RefType<any, any, any>
+  | EnumType<EnumTypeParamShape>
+  | CustomType<CustomTypeParamShape>
+>;
+
+type InternalModelFields = Record<
+  string,
+  InternalField | InternalRelationalField
+>;
+
+type ModelData = {
+  fields: ModelFields;
+  identifier: string[];
+  secondaryIndexes: ReadonlyArray<ModelIndexType<any, any, any, any, any>>;
+  authorization: Authorization<any, any, any>[];
+};
+
+type InternalModelData = ModelData & {
+  fields: InternalModelFields;
+  identifier: string[];
+  secondaryIndexes: ReadonlyArray<InternalModelIndexType>;
+  authorization: Authorization<any, any, any>[];
+};
+
+export type ModelTypeParamShape = {
+  fields: ModelFields;
+  identifier: string[];
+  secondaryIndexes: ReadonlyArray<SecondaryIndexIrShape>;
+  authorization: Authorization<any, any, any>[];
+};
+
+// Extract field names that can be used to define a secondary index PK or SK
+// i.e., nullable string or nullable number fields
+type SecondaryIndexFields<T extends Record<string, unknown>> = keyof {
+  [Field in keyof T as NonNullable<T[Field]> extends string | number
+    ? Field
+    : never]: T[Field];
+} &
+  string;
+
+type ExtractType<T extends ModelTypeParamShape> = {
+  [FieldProp in keyof T['fields'] as T['fields'][FieldProp] extends ModelField<
+    any,
+    any,
+    any
+  >
+    ? FieldProp
+    : never]: T['fields'][FieldProp] extends ModelField<infer R, any, any>
+    ? R
+    : never;
+};
+
+type GetRequiredFields<T> = {
+  [FieldProp in keyof T as T[FieldProp] extends NonNullable<T[FieldProp]>
+    ? FieldProp
+    : never]: T[FieldProp];
+};
+
+type IdentifierMap<T extends ModelTypeParamShape> = GetRequiredFields<
+  ExtractType<T>
+>;
+
+// extracts model fields that CAN BE used as identifiers (scalar, non-nullable fields)
+// TODO: make this also filter out all non-scalars e.g., model fields and custom types
+type IdentifierFields<T extends ModelTypeParamShape> = keyof IdentifierMap<T> &
+  string;
+
+type IdentifierType<
+  T extends ModelTypeParamShape,
+  Fields extends string = IdentifierFields<T>,
+> = Array<Fields>;
+
+/**
+ * For a given ModelTypeParamShape, produces a map of Authorization rules
+ * that would *conflict* with the given type.
+ *
+ * E.g.,
+ *
+ * ```
+ * const test = {
+ *  fields: {
+ *   title: fields.string(),
+ *   otherfield: fields.string().array(),
+ *   numfield: fields.integer(),
+ *  },
+ *  identifier: [],
+ *  authorization: [],
+ * };
+ *
+ * ConflictingAuthRulesMap<typeof test> === {
+ *  title: Authorization<"title", true>;
+ *  otherfield: Authorization<"otherfield", false>;
+ *  numfield: Authorization<"numfield", true> | Authorization<"numfield", false>;
+ * }
+ * ```
+ */
+type ConflictingAuthRulesMap<T extends ModelTypeParamShape> = {
+  [K in keyof ExtractType<T>]: K extends string
+    ? string extends ExtractType<T>[K]
+      ? Authorization<any, K, true>
+      : string[] extends ExtractType<T>[K]
+        ? Authorization<any, K, false>
+        : Authorization<any, K, true> | Authorization<any, K, false>
+    : never;
+};
+
+export type AddRelationshipFieldsToModelTypeFields<
+  Model,
+  RelationshipFields extends Record<
+    string,
+    ModelRelationalField<ModelRelationalFieldParamShape, string, any, any>
+  >,
+> =
+  Model extends ModelType<
+    infer ModelParam extends ModelTypeParamShape,
+    infer HiddenKeys
+  >
+    ? ModelType<
+        SetTypeSubArg<
+          ModelParam,
+          'fields',
+          ModelParam['fields'] & RelationshipFields
+        >,
+        HiddenKeys
+      >
+    : never;
+
+/**
+ * For a given ModelTypeParamShape, produces a union of Authorization rules
+ * that would *conflict* with the given type.
+ *
+ * E.g.,
+ *
+ * ```
+ * const test = {
+ *  fields: {
+ *   title: fields.string(),
+ *   otherfield: fields.string().array(),
+ *   numfield: fields.integer(),
+ *  },
+ *  identifier: [],
+ *  authorization: [],
+ * };
+ *
+ * ConflictingAuthRules<typeof test> ===
+ *  Authorization<"title", true>
+ *  | Authorization<"otherfield", false>
+ *  | Authorization<"numfield", true> | Authorization<"numfield", false>
+ * ;
+ * ```
+ */
+type _ConflictingAuthRules<T extends ModelTypeParamShape> =
+  ConflictingAuthRulesMap<T>[keyof ConflictingAuthRulesMap<T>];
+
+export type ModelType<
+  T extends ModelTypeParamShape,
+  K extends keyof ModelType<T> = never,
+> = Omit<
+  {
+    identifier<ID extends IdentifierType<T> = []>(
+      identifier: ID,
+    ): ModelType<SetTypeSubArg<T, 'identifier', ID>, K | 'identifier'>;
+    secondaryIndexes<
+      const SecondaryIndexPKPool extends string = SecondaryIndexFields<
+        ExtractType<T>
+      >,
+      const Indexes extends readonly ModelIndexType<
+        string,
+        string,
+        unknown,
+        readonly [],
+        any
+      >[] = readonly [],
+      const IndexesIR extends readonly any[] = SecondaryIndexToIR<
+        Indexes,
+        ExtractType<T>
+      >,
+    >(
+      callback: (
+        index: <PK extends SecondaryIndexPKPool>(
+          pk: PK,
+        ) => ModelIndexType<
+          SecondaryIndexPKPool,
+          PK,
+          ReadonlyArray<Exclude<SecondaryIndexPKPool, PK>>
+        >,
+      ) => Indexes,
+    ): ModelType<
+      SetTypeSubArg<T, 'secondaryIndexes', IndexesIR>,
+      K | 'secondaryIndexes'
+    >;
+    authorization<AuthRuleType extends Authorization<any, any, any>>(
+      callback: (allow: Omit<AllowModifier, 'resource'>) => AuthRuleType | AuthRuleType[],
+    ): ModelType<
+      SetTypeSubArg<T, 'authorization', AuthRuleType[]>,
+      K | 'authorization'
+    >;
+  },
+  K
+> &
+  Brand<typeof brandName>;
+
+/**
+ * External representation of Model Type that exposes the `addRelationships` modifier.
+ * Used on the complete schema object.
+ */
+export type SchemaModelType<
+  T extends ModelType<ModelTypeParamShape, never | 'identifier'> = ModelType<
+    ModelTypeParamShape,
+    never | 'identifier'
+  >,
+  ModelName extends string = string,
+  IsRDS extends boolean = false,
+> = IsRDS extends true
+  ? T & {
+      addRelationships<
+        Param extends Record<
+          string,
+          ModelRelationalField<any, string, any, any>
+        > = Record<never, never>,
+      >(
+        relationships: Param,
+      ): Record<ModelName, Param>;
+      fields: T extends ModelType<infer R extends ModelTypeParamShape, any>
+        ? R['fields']
+        : never;
+    }
+  : T;
+
+/**
+ * Internal representation of Model Type that exposes the `data` property.
+ * Used at buildtime.
+ */
+export type InternalModel = SchemaModelType<
+  ModelType<ModelTypeParamShape>,
+  string,
+  true
+> & {
+  data: InternalModelData;
+};
+
+function _model<T extends ModelTypeParamShape>(fields: T['fields']) {
+  const data: ModelData = {
+    fields,
+    identifier: ['id'],
+    secondaryIndexes: [],
+    authorization: [],
+  };
+
+  const builder = {
+    identifier(identifier) {
+      data.identifier = identifier;
+
+      return this;
+    },
+    secondaryIndexes(callback) {
+      data.secondaryIndexes = callback(modelIndex);
+
+      return this;
+    },
+    authorization(callback) {
+      const { resource: _, ...rest } = allow;
+      const rules = callback(rest);
+      data.authorization = Array.isArray(rules) ? rules : [rules];
+
+      return this;
+    },
+    ...brand(brandName),
+  } as ModelType<T>;
+
+  return {
+    ...builder,
+    data,
+    addRelationships(relationships) {
+      data.fields = { ...data.fields, ...relationships };
+    },
+    fields: data.fields,
+  } as InternalModel as ModelType<T>;
+}
+
+/**
+ * Model Type type guard
+ * @param modelType - api-next ModelType
+ * @returns true if the given value is a ModelSchema
+ */
+export const isSchemaModelType = (
+  modelType: any | SchemaModelType,
+): modelType is SchemaModelType => {
+  const internalType = modelType as InternalModel;
+  return (
+    typeof internalType === 'object' &&
+    internalType.data !== undefined &&
+    internalType.data.fields !== undefined &&
+    internalType.data.authorization !== undefined &&
+    internalType.data.identifier !== undefined &&
+    internalType.data.secondaryIndexes !== undefined &&
+    typeof internalType.addRelationships === 'function'
+  );
+};
+
+/**
+ * A data model that creates a matching Amazon DynamoDB table and provides create, read (list and get), update,
+ * delete, and subscription APIs.
+ *
+ * @param fields database table fields. Supports scalar types and relationship types.
+ * @returns a data model definition
+ */
+export function model<T extends ModelFields>(
+  fields: T,
+): ModelType<{
+  fields: T;
+  identifier: Array<'id'>;
+  secondaryIndexes: [];
+  authorization: [];
+}> {
+  return _model(fields);
+}

package/src/RefType.ts

@@ -0,0 +1,139 @@
+import { SetTypeSubArg } from '@aws-amplify/data-schema-types';
+import { Brand } from './util';
+import { AllowModifier, Authorization, allow } from './Authorization';
+import { __auth } from './ModelField';
+
+const brandName = 'ref';
+
+type RefTypeData = {
+  type: 'ref';
+  link: string;
+  valueRequired: boolean;
+  array: boolean;
+  arrayRequired: boolean;
+  mutationOperations: MutationOperations[];
+  authorization: Authorization<any, any, any>[];
+};
+
+export type RefTypeParamShape = {
+  type: 'ref';
+  link: string;
+  valueRequired: boolean;
+  array: boolean;
+  arrayRequired: boolean;
+  authorization: Authorization<any, any, any>[];
+};
+
+type MutationOperations = 'create' | 'update' | 'delete';
+
+export type RefType<
+  T extends RefTypeParamShape,
+  K extends keyof RefType<T> = never,
+  Auth = undefined,
+  // Branding the exported type allows us to detect it
+  // nominally in our mapped types, ignoring structural overlap with other types
+> = Omit<
+  {
+    /**
+     * Marks a field as required.
+     */
+    required(): RefType<
+      SetTypeSubArg<
+        T,
+        T['array'] extends true ? 'arrayRequired' : 'valueRequired',
+        true
+      >,
+      K | 'required'
+    >;
+    /**
+     * Marks a field as an array of the specified ref type.
+     */
+    array(): RefType<
+      SetTypeSubArg<T, 'array', true>,
+      Exclude<K, 'required'> | 'array'
+    >;
+    /**
+     * Configures field-level authorization rules. Pass in an array of authorizations `(a.allow.____)` to mix and match
+     * multiple authorization rules for this field.
+     */
+    authorization<AuthRuleType extends Authorization<any, any, any>>(
+      callback: (allow: AllowModifier) => AuthRuleType | AuthRuleType[],
+    ): RefType<T, K | 'authorization', AuthRuleType>;
+
+    mutations(operations: MutationOperations[]): RefType<T, K | 'mutations'>;
+  },
+  K
+> & {
+  // This is a lie. This property is never set at runtime. It's just used to smuggle auth types through.
+  [__auth]?: Auth;
+} & Brand<typeof brandName>;
+
+function brandedBuilder<T extends RefTypeParamShape>(
+  builder: Record<keyof RefType<T> & string, any>,
+): RefType<T> {
+  return builder as RefType<T>;
+}
+
+/**
+ * Internal representation of Ref that exposes the `data` property.
+ * Used at buildtime.
+ */
+export type InternalRef = RefType<RefTypeParamShape> & {
+  data: RefTypeData;
+};
+
+function _ref<T extends RefTypeParamShape>(link: T['link']) {
+  const data: RefTypeData = {
+    type: 'ref',
+    link,
+    valueRequired: false,
+    array: false,
+    arrayRequired: false,
+    mutationOperations: [],
+    authorization: [],
+  };
+
+  const builder: RefType<T> = brandedBuilder({
+    required() {
+      if (data.array) {
+        data.arrayRequired = true;
+      } else {
+        data.valueRequired = true;
+      }
+
+      return this;
+    },
+    array() {
+      data.array = true;
+
+      return this;
+    },
+    authorization<AuthRuleType extends Authorization<any, any, any>>(
+      callback: (allow: AllowModifier) => AuthRuleType | AuthRuleType[],
+    ) {
+      const rules = callback(allow);
+      data.authorization = Array.isArray(rules) ? rules : [rules];
+
+      return this;
+    },
+    mutations(operations: MutationOperations[]) {
+      data.mutationOperations = operations;
+      return this;
+    },
+  });
+
+  return { ...builder, data } as InternalRef as RefType<T>;
+}
+
+type RefTypeArgFactory<Link extends string> = {
+  type: 'ref';
+  link: Link;
+  valueRequired: false;
+  array: false;
+  arrayRequired: false;
+  authorization: [];
+};
+
+export function ref<Value extends string, T extends Value>(link: T) {
+  return _ref<RefTypeArgFactory<T>>(link);
+}