docs(improve): add better doc

for attribute2 and update2 functions to describe the typing enhancement

Author: michaelwittwer

src/dynamo/expression/condition-expression-builder.ts

@@ -287,8 +287,7 @@ function validateForOperator(operator: ConditionOperator, values?: any[]) {
     if (values && Array.isArray(values) && values.length) {
       validateValues(operator, values)
     } else {
-      // TODO
-      throw new Error('blub')
+      throw new Error(dynamicTemplate(ERR_ARITY_DEFAULT, {parameterArity: operatorParameterArity(operator), operator}))
     }
   }
 }

src/dynamo/expression/logical-operator/attribute.function.ts

@@ -5,17 +5,35 @@ import {
   ConditionExpressionDefinitionChainTyped,
 } from '../type/condition-expression-definition-chain'
 
-
 /**
- * Use this method when accessing a top level attribute of a model
+ * Use this method when accessing a top level attribute of a model with strict typing of the value in chained function
+ *
+ * ```typescript
+ * @Model()
+ * class Person{
+ *
+ *   @PartitionKeyUUID()
+ *   id: string
+ *   age: number
+ * }
+ *
+ * store
+ *  .scan()
+ *  .where(attribute2(Person, 'age').equals(5))
+ *  .exec()
+ * ```
+ *
+ * When using the attribute2 we have type support for the equals (and all other condition functions) value,
+ * it can only be number, because the type of age is number too, this only works when not using a custom mapper.
+ * The downside of the strict typing is the model constructor parameter which is only required for typing reasons
  */
 export function attribute2<T, K extends keyof T>(modelConstructor: ModelConstructor<T>, attributePath: K)
   : ConditionExpressionDefinitionChainTyped<T, K> {
   return propertyDefinitionFunction<T, K>(attributePath)
 }
 
 /**
- * Use this method when accessing a top level attribute of a model
+ * Use this method when accessing a top level attribute of a model to have type checking of the attributePath
  */
 export function attribute<T>(attributePath: keyof T): ConditionExpressionDefinitionChain
 

src/dynamo/expression/logical-operator/update.function.ts

@@ -6,7 +6,25 @@ import {
 } from '../type/update-expression-definition-chain'
 
 /**
- * Use this method when accessing a top level attribute of a model
+ * Use this method when accessing a top level attribute of a model with strict typing of the value in chained function
+ *
+ * ```typescript
+ * @Model()
+ * class Person{
+ *
+ *   @PartitionKeyUUID()
+ *   id: string
+ *   age: number
+ * }
+ *
+ * store.update('idValue')
+ *  .operations(update2(SimpleWithPartitionKeyModel, 'age').set(5))
+ *  .exec()
+ * ```
+ *
+ * When using the update2 we have type support for the set (and all other update functions) value,
+ * it can only be number, because the type of age is number too, this only works when not using a custom mapper.
+ * The downside of the strict typing is the model constructor parameter which is only required for typing reasons.
  */
 export function update2<T, K extends keyof T>(
   modelConstructor: ModelConstructor<T>,
@@ -16,7 +34,7 @@ export function update2<T, K extends keyof T>(
 }
 
 /**
- * Use this method when accessing a top level attribute of a model
+ * Use this method when accessing a top level attribute of a model to have type checking for attributePath
  */
 export function update<T>(attributePath: keyof T): UpdateExpressionDefinitionChain
 

src/dynamo/expression/param-util.ts

@@ -5,7 +5,7 @@ import { resolveAttributeValueNameConflicts } from './functions/resolve-attribut
 import { Expression } from './type'
 import { UpdateActionKeyword } from './type/update-action-keyword.type'
 
-export function addUpdateExpression(updateExpression: Expression, params: UpdateItemInput) {
+export function addUpdateExpression(updateExpression: Expression, params: UpdateItemInput): void {
   addExpression('UpdateExpression', updateExpression, params)
 }
 
@@ -48,11 +48,23 @@ export function addExpression(
   }
 }
 
+type UpdateExpressionsByKeyword = Record<UpdateActionKeyword, string>
 
-type UpdateExpressionsByKeyword = {
-  [key in UpdateActionKeyword]: string
-}
 
+/**
+ * Will merge two update expressions into one, one action keyword can only appear once in an update expression
+ *
+ * ```
+ * const merged = mergeUpdateExpressions(
+ *                    'SET a, b REMOVE e, f ADD i, j DELETE m, n',
+ *                    'SET c, d REMOVE g, h ADD k, l DELETE o, p',
+ *                )
+ * console.log(merged) -> 'SET a, b, c, d REMOVE e, f, g, h ADD i, j, k, l DELETE m, n, o, p'
+ * ```
+ *
+ * @param expression1
+ * @param expression2
+ */
 export function mergeUpdateExpressions(expression1: string, expression2: string): string {
   const a = splitUpdateExpressionToActionKeyword(expression1)
   const b = splitUpdateExpressionToActionKeyword(expression2)
@@ -61,6 +73,9 @@ export function mergeUpdateExpressions(expression1: string, expression2: string)
     .join(' ')
 }
 
+/**
+ * Will return an object containing all the update statements mapped to an update action keyword
+ */
 function splitUpdateExpressionToActionKeyword(updateExpression: string): UpdateExpressionsByKeyword {
   // add a whitespace at the beginning of the expression to be able to work with a more stricter regex
   return ` ${updateExpression}`
@@ -70,7 +85,10 @@ function splitUpdateExpressionToActionKeyword(updateExpression: string): UpdateE
     .reduce((u, e, i, arr) => {
       if (isUpdateActionKeyword(e)) {
         u[e] = arr[i + 1]
+      } else {
+        throw new Error(`unknown action keyword ${e}`)
       }
+
       return u
     }, <UpdateExpressionsByKeyword>{})
 }