refactor(collection-mapper): make the mapping more consistent

BREAKING CHANGE
some mappings will no longer work due to missing information for a correct parsing
without decorator, collections are consistently mapped as follows:
- Array  <-->  [L]ist
- Set<number|string|Binary>   <-->  [(N|S|B)S]et

Set<ComplextType> --> is no longer mapped to [L]ist, only possible with decorator

Author: mumenthalers

src/decorator/decorators.spec.ts

@@ -19,7 +19,8 @@ import {
   SimpleModel,
 } from '../../test/models'
 import { Form } from '../../test/models/real-world'
-import { GSIPartitionKey, GSISortKey, LSISortKey, PartitionKey, Property, SortedSet, SortKey, Transient } from './impl'
+import { GSIPartitionKey, GSISortKey, LSISortKey, PartitionKey, Property, SortKey, Transient } from './impl'
+import { CollectionProperty } from './impl/collection/collection-property.decorator'
 import { Model } from './impl/model/model.decorator'
 import { Metadata, metadataForClass, metadataForModel, ModelMetadata } from './index'
 import { metadataForProperty } from './metadata'
@@ -370,7 +371,7 @@ describe('Decorators should add correct metadata', () => {
 
       @Model()
       class B extends A {
-        @SortedSet()
+        @CollectionProperty({ sorted: true })
         myOwnProp: string[]
       }
 

src/decorator/impl/collection/collection-property-data.model.ts

@@ -0,0 +1,29 @@
+import { BinaryAttribute, MapperForType, NumberAttribute, StringAttribute } from '../../../mapper'
+import { ModelConstructor } from '../../../model'
+
+export interface CollectionPropertyDataBase<R, T extends StringAttribute | NumberAttribute | BinaryAttribute> {
+  /**
+   * the name of property how it is named in dynamoDB
+   */
+  name?: string
+
+  /**
+   * if the collection should preserve the order. if so it will be stored as (L)ist
+   */
+  sorted?: boolean
+
+  /**
+   * provide an itemMapper if you want your complex items being mapped to String|Number|Binary attribute
+   * (e.g. because you can't store it in a (S)et otherwise)
+   * only provide either itemMapper or itemType --> not both
+   * itemMapper is basically intended to be used with [S]et. though it also works with [L]ist
+   */
+  itemMapper?: MapperForType<R, T>
+
+  /**
+   * provide an itemType (class with @Model decorator) for complex types (eg. Set<ComplexType>)
+   * collections with complex types will be stored as (L)ist
+   * only provide either itemType or itemMapper --> not both
+   */
+  itemType?: ModelConstructor<any>
+}

src/decorator/impl/collection/collection-property.decorator.ts

@@ -0,0 +1,65 @@
+import { BinaryAttribute, MapperForType, NumberAttribute, StringAttribute } from '../../../mapper'
+import {
+  wrapMapperForDynamoListJsArray,
+  wrapMapperForDynamoListJsSet,
+  wrapMapperForDynamoSetJsArray,
+  wrapMapperForDynamoSetJsSet,
+} from '../../../mapper/wrap-mapper-for-collection.function'
+import { ModelConstructor } from '../../../model'
+import { PropertyMetadata, TypeInfo } from '../../metadata'
+import { getMetadataType } from '../../util'
+import { initOrUpdateProperty } from '../property/init-or-update-property.function'
+import { CollectionPropertyDataBase } from './collection-property-data.model'
+
+type DecoratorFn = (target: object, propertyKey: string | symbol) => void
+
+export function CollectionProperty<R, T extends StringAttribute | NumberAttribute | BinaryAttribute>(opts: CollectionPropertyDataBase<R, T> = {}): DecoratorFn {
+  return (target: object, propertyKey: string | symbol) => {
+    if (typeof propertyKey === 'string') {
+
+      const type: ModelConstructor<any> = getMetadataType(target, propertyKey)
+
+      if (type !== Set && type !== Array) {
+        throw new Error(`[${target.constructor.name}::${propertyKey}] The CollectionProperty decorator is meant for properties of type Set or Array`)
+      }
+
+      const meta: Partial<PropertyMetadata<any>> & { typeInfo: TypeInfo } = {
+        name: propertyKey,
+        nameDb: opts && opts.name || propertyKey,
+        typeInfo: {
+          type,
+          isCustom: true,
+        },
+        isSortedCollection: !!opts.sorted,
+      }
+
+      const hasItemType = 'itemType' in opts && !!opts.itemType
+      const hasItemMapper = 'itemMapper' in opts && !!opts.itemMapper
+
+      if (hasItemMapper && hasItemType) {
+        throw new Error(`[${target.constructor.name}::${propertyKey}] provide either itemType or itemMapper, not both`)
+      }
+
+      if (hasItemType) {
+        meta.typeInfo.genericType = opts.itemType
+      }
+
+      if (hasItemMapper) {
+        const itemMapper = <MapperForType<any, any>>opts.itemMapper
+
+        const wrappedMapper: MapperForType<any, any> = type === Array
+          ? !!opts.sorted
+            ? wrapMapperForDynamoListJsArray(itemMapper)
+            : wrapMapperForDynamoSetJsArray(itemMapper)
+          : !!opts.sorted
+            ? wrapMapperForDynamoListJsSet(itemMapper)
+            : wrapMapperForDynamoSetJsSet(itemMapper)
+
+        meta.mapper = () => wrappedMapper
+        meta.mapperForSingleItem = () => itemMapper
+      }
+
+      initOrUpdateProperty(meta, target, propertyKey)
+    }
+  }
+}

src/decorator/impl/collection/sorted-set.decorator.ts

@@ -6,6 +6,7 @@ import { initOrUpdateProperty } from '../property/init-or-update-property.functi
  * Only the L(ist) dynamo datatype preservers the order of inserted items, so we have to make sure the L(ist) type is used
  * when persisting. The modelConstructor is required if the collection items
  * have some property decorators, so we can retrieve this information using the model class.
+ * @deprecated instead use @CollectionProperty({ sorted: true, itemType?: ModelConstructor })
  */
 export function SortedSet(modelConstructor?: ModelConstructor<any>): PropertyDecorator {
   return (target: any, propertyKey: string | symbol) => {

src/decorator/impl/collection/typed-array.decorator.ts

@@ -5,6 +5,7 @@ import { initOrUpdateProperty } from '../property/init-or-update-property.functi
 /**
  * Makes sure the property will be mapped to a L(ist) type. The modelConstructor is required if the collection items
  * have some property decorators, so we can retrieve this information using the model class.
+ * @deprecated instead use @CollectionProperty({ itemType?: ModelConstructor })
  */
 export function TypedArray<T>(modelConstructor?: ModelConstructor<T>): PropertyDecorator {
   return (target: object, propertyKey: string | symbol) => {

src/decorator/impl/collection/typed-set.decorator.ts

@@ -5,6 +5,7 @@ import { initOrUpdateProperty } from '../property/init-or-update-property.functi
 /**
  * Makes sure the property will be marshalled to a S(et) type. The modelConstructor is required if the collection items
  * have some property decorators, so we can retrieve this information using the model class.
+ * @deprecated instead use @CollectionProperty({ itemType?: modelConstructor })
  */
 export function TypedSet(modelConstructor?: ModelConstructor<any>): PropertyDecorator {
   return (target: any, propertyKey: string | symbol) => {

src/decorator/impl/custom-mapper/custom-mapper.decorator.ts

@@ -1,6 +1,11 @@
 import { MapperForType } from '../../../mapper'
 import { initOrUpdateProperty } from '../property/init-or-update-property.function'
 
+/**
+ *
+ * @param customMapper
+ * @deprecated use @Property({mapper: YourCustomMapper}) instead
+ */
 export function CustomMapper(customMapper: MapperForType<any, any>): PropertyDecorator {
   return (target: any, propertyKey: string | symbol) => {
     if (typeof propertyKey === 'string') {

src/decorator/impl/property/property-data.model.ts

@@ -1,4 +1,7 @@
+import { MapperForType } from '../../../mapper'
+
 export interface PropertyData {
   // the name of property how it is named in dynamoDB
   name: string
+  mapper: MapperForType<any, any>
 }

src/decorator/impl/property/property.decorator.ts

@@ -9,6 +9,12 @@ export function Property(opts: Partial<PropertyData> = {}): PropertyDecorator {
         name: propertyKey,
         nameDb: opts.name || propertyKey,
       }
+
+      if ('mapper' in opts && !!opts.mapper) {
+        const m = opts.mapper
+        propertyOptions.mapper = () => m
+      }
+
       initOrUpdateProperty(propertyOptions, target, propertyKey)
     }
   }

src/decorator/metadata/property-metadata.model.ts

@@ -1,7 +1,6 @@
-import { MapperForType } from '../../mapper/for-type/base.mapper'
-
 // def good
 import * as DynamoDB from 'aws-sdk/clients/dynamodb'
+import { MapperForType } from '../../mapper/for-type/base.mapper'
 import { Attribute } from '../../mapper/type/attribute.type'
 import { ModelConstructor } from '../../model/model-constructor'
 
@@ -40,6 +39,8 @@ export interface PropertyMetadata<T, R extends Attribute = Attribute> {
 
   mapper?: () => MapperForType<any, R>
 
+  mapperForSingleItem?: () => MapperForType<any, any>
+
   // maps the index name to the key type to describe for which GSI this property describes a key attribute
   keyForGSI?: Record<string, DynamoDB.KeyType>
 
@@ -55,3 +56,16 @@ export function hasGenericType(
 ): propertyMetadata is PropertyMetadata<any, any> & { typeInfo: { genericType: ModelConstructor<any> } } {
   return !!(propertyMetadata && propertyMetadata.typeInfo && propertyMetadata.typeInfo.genericType)
 }
+
+export function alterCollectionPropertyMetadataForSingleItem<T>(propertyMeta?: PropertyMetadata<T> | null): PropertyMetadata<T> | undefined {
+  if (!propertyMeta) {
+    return
+  }
+  if (propertyMeta.mapper && propertyMeta.mapperForSingleItem) {
+    return { ...propertyMeta, mapper: propertyMeta.mapperForSingleItem }
+  }
+  if (propertyMeta.typeInfo && (propertyMeta.typeInfo.type === Set || propertyMeta.typeInfo.type === Array)) {
+    return
+  }
+  return { ...propertyMeta }
+}