import { DocumentClient } from 'aws-sdk/clients/dynamodb'; import { Fields } from './Fields'; import { Table } from './Table'; import { Update } from './Update'; import { Condition } from './Condition'; /** * The Model object that wraps access to the DynamoDB table and makes it easy to map table data to * and from model data. * * @example [examples/Model.ts]{@link https://github.com/jasoncraftscode/dynamodb-datamodel/tree/main/examples/Model.ts} (imports: [examples/Table.ts]{@link https://github.com/jasoncraftscode/dynamodb-datamodel/tree/main/examples/Table.ts}) * ```typescript * [[include:Model.ts]] * ``` * * @public */ export declare class Model implements Model.ModelBase { /** * The type name of the model. Used by {@link Fields."type"} to set a type attribute. */ name?: string; /** * Schema to use for mapping data between the model and table data. */ schema: Model.ModelSchema; /** * Table to used for reading and writing model data to dynamodb. */ table: Table; /** * Initialize this class with params. * @param params - Params to initialize this class with. */ constructor(params: Model.ModelParams); /** * Converts table item data to model data. Method called from the in the model methods after reading or * writing data to the table to convert the item and attribute output to model properties. * @param data - Table item data to convert to model data. * @param context - Context used for converting table to model data, passed to each field object. * @returns Model data converted from the table data. */ toModel(data: Table.AttributeValuesMap | undefined, context: Fields.ModelContext): Model.ModelOut; /** * Converts model data to table data. Methods called called from the model methods before reading or * writing data to the table, to convert the model data to the table data. * @param data - Model data to convert to table data. * @param context - Context used for converting model to table data, passed to each field object. * @returns Table data converted from the model data. */ toTable(data: Model.ModelData, context: Fields.TableContext): Model.TableData; /** * Converts model update data to table update data, similar to {@link toTable} but since table updates * supports attribute based update expressions updates are handled differently then other actions. * @param data - Model update data to convert to table update data. * @param context - Context used for converting model to table data, passed to each field object. * @returns Table data converted from the model data. */ toTableUpdate(data: Model.ModelUpdate, context: Fields.TableContext): Model.TableUpdateData; /** * Generate the context used in {@link toModel}, {@link toTable} and {@link toTableUpdate}. * @param action - Type of table item action is currently executing. * @param options - Options used when reading or writing to the table. */ getContext(action: Table.ItemActions, options: Table.WriteOptions, scope?: Fields.ActionScope, conditions?: Condition.Resolver[]): Fields.TableContext; /** * Creates the params that can be used when calling [DocumentClient.get]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#get-property}. * @param key - Model key of the item to get. * @param options - Additional optional options to use for get. * @returns Input params for [DocumentClient.get]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#get-property}. */ getParams(key: Model.ModelCore, options?: Table.GetOptions): DocumentClient.GetItemInput; /** * Creates the params that can be used when calling [DocumentClient.delete]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#delete-property}. * @param key - Model key of the item to delete. * @param options - Additional optional options to use for delete. * @returns Input params for [DocumentClient.delete]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#delete-property}. */ deleteParams(key: Model.ModelCore, options?: Table.DeleteOptions): DocumentClient.DeleteItemInput; /** * Creates the params that can be used when calling [DocumentClient.put]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#put-property}. * @param item - Model item data to put. * @param options - Additional optional options to use for put. * @returns Input params for [DocumentClient.put]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#put-property}. */ putParams(item: Model.ModelCore, options?: Table.PutOptions): DocumentClient.PutItemInput; /** * Creates the params that can be used when calling [DocumentClient.update]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#update-property}. * @param item - Model item data or update resolver to update. * @param options - Additional optional options to use for update. * @returns Input params for [DocumentClient.update]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#update-property}. */ updateParams(item: Model.ModelUpdate, options?: Table.UpdateOptions): DocumentClient.UpdateItemInput; /** * Wrapper method for [DocumentClient.get]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#get-property} method. * That uses the model as input and output. * @param key - Model key of item to get. * @param options - Additional optional options to use for get. * @returns An async promise that contains the model data and the table get result object. */ get(key: Model.ModelCore, options?: Table.GetOptions): Promise; /** * Wrapper method for [DocumentClient.delete]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#delete-property} method. * That uses the model as input and output. * @param key - Model key of item to delete. * @param options - Additional optional options to use for delete. * @returns An async promise that contains the model data and the table delete result object. */ delete(key: Model.ModelCore, options?: Table.DeleteOptions): Promise; /** * Adds the model item to the table and ensures it doesn't already exists. * See {@link put} for params details. */ create(data: Model.ModelCore, options?: Table.PutOptions): Promise; /** * Replaces the model item in the table only if it already exists. * See {@link put} for details. */ replace(data: Model.ModelCore, options?: Table.PutOptions): Promise; /** * Wrapper method for [DocumentClient.put]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#put-property} method. * That uses the model as input and output. * @param item - Model data of the item to put. * @param options - Additional optional options to use for put. * @returns An async promise that contains the model data and the table put result object. */ put(data: Model.ModelCore, options?: Table.PutOptions): Promise; /** * Wrapper method for [DocumentClient.update]{@link https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#update-property} method. * That uses the model as input and output. * @param item - Model data of the item to update. * @param options - Additional optional options to use for update. * @returns An async promise that contains the model data and the table update result object. */ update(data: Model.ModelUpdate, options?: Table.UpdateOptions): Promise; /** * Adds a get item by key to a batch get operation. * @param batchGet - BatchGet operation to added this key to. * @param key - Key of item to fetch in BatchGet. * @returns Object to get the resulting item from the BatchGet result. */ addBatchGet(batchGet: Table.BatchGet, key: Model.ModelCore): Model.ModelResult; /** * Adds a delete item by key to a batch write operation. * @param batchWrite - BatchWrite operation to added this key to. * @param key - Key of item to delete in BatchWrite. * @returns Object to get the resulting item from the BatchWrite result. */ addBatchDelete(batchWrite: Table.BatchWrite, key: Model.ModelCore): Model.ModelResult; /** * Adds a put item to a batch write operation. * @param batchWrite - BatchWrite operation to added this key to. * @param item - Item added to the batch write operation. * @returns Object to get the resulting item from the BatchWrite result. */ addBatchPut(batchWrite: Table.BatchWrite, item: Model.ModelData): Model.ModelResult; /** * Adds a get item to a transact get operation. * @param transactGet - TransactGet operation to added this key to. * @param key - Key of item to fetch in BatchGet. * @param itemAttributes - List of attributes to fetch in TransactGet, if this is empty then all item attributes are return. * @returns Object to get the resulting item from the TransactGet result. */ addTransactGet(transactGet: Table.TransactGet, key: Model.ModelCore, itemAttributes?: string[]): Model.ModelResult; /** * Adds an item condition check to a transact write operation. * @param transactWrite - TransactWrite operation to added this item condition check to. * @param key - Key of item to used in condition check. * @param conditions - List of conditions to validate when executing the transact write. * @param returnFailure - Determines what to return on transaction failure. * @returns Object to get the resulting item from the TransactWrite result. */ addTransactCheck(transactWrite: Table.TransactWrite, key: Model.ModelCore, conditions: Condition.Resolver[], returnFailure?: DocumentClient.ReturnValuesOnConditionCheckFailure): Model.ModelResult; /** * Adds an item delete to a transact write operation. * @param transactWrite - TransactWrite operation to added this delete item to. * @param key - Key of item to delete in transact write. * @param conditions - List of conditions to validate when executing the transact write. * @param returnFailure - Determines what to return on transaction failure. * @returns Object to get the resulting item from the TransactWrite result. */ addTransactDelete(transactWrite: Table.TransactWrite, key: Model.ModelCore, conditions?: Condition.Resolver[], returnFailure?: DocumentClient.ReturnValuesOnConditionCheckFailure): Model.ModelResult; /** * Adds an item put to a transact write operation. * @param transactWrite - TransactWrite operation to added this put item to. * @param item - Item to put in the transact write. * @param conditions - List of conditions to validate when executing the transact write. * @param returnFailure - Determines what to return on transaction failure. * @returns Object to get the resulting item from the TransactWrite result. */ addTransactPut(transactWrite: Table.TransactWrite, item: Model.ModelData, conditions?: Condition.Resolver[], returnFailure?: DocumentClient.ReturnValuesOnConditionCheckFailure): Model.ModelResult; /** * Adds an item update to a transact write operation. * @param transactWrite - TransactWrite operation to added this update item to. * @param item - Item to update in transact write. * @param conditions - List of conditions to validate when executing the transact write. * @param returnFailure - Determines what to return on transaction failure. * @returns Object to get the resulting item from the TransactWrite result. */ addTransactUpdate(transactWrite: Table.TransactWrite, item: Model.ModelUpdate, conditions?: Condition.Resolver[], returnFailure?: DocumentClient.ReturnValue): Model.ModelResult; /** * Helper method that splits the table data into a key and item. * @param table - Table used to determine what attributes are keys. * @param data - Table data to split into key and item. * @returns The key, item and raw converted model data. */ static splitTableData(table: Table, data: Table.AttributeValuesMap): Model.TableData; /** * Initializes each field in the schema with the model and associated property name. * @param schema - Model schema to initialize. * @param model - Model to use when initialize each field in the schema. */ static initSchema(schema: Model.ModelSchema, model: Model): void; } /** * Is also a namespace for scoping Model based interfaces and types. * @public * */ export declare namespace Model { /** * Interface used in {@link Field.init}. */ interface ModelBase { /** * The type name of the model. Used by {@link Fields."type"} to set a type attribute. */ name?: string; /** * Schema to use for mapping data between the model and table data. */ schema: Model.ModelSchema; /** * Table to used for reading and writing model data to dynamodb. */ table: Table; } /** * Types supported by the Model. */ type ModelType = number | string | boolean | null | object; /** * Item data supported by the Model. */ type ModelData = { [key: string]: ModelType; }; /** * Data returned from {@link Model.toTable}. */ interface TableData { /** All item table attributes. */ data: Table.AttributeValuesMap; /** Primary key for item. */ key: Table.PrimaryKey.AttributeValuesMap; /** Rest of the item attributes. */ item?: Table.AttributeValuesMap; } /** * Data returned from {@link Model.toTableUpdate}. */ interface TableUpdateData { /** All item table update attributes. */ data: Update.ResolverMap; /** Primary key for item. */ key: Table.PrimaryKey.AttributeValuesMap; /** Rest of the item update attributes. */ item?: Update.ResolverMap; } /** * Params used when creating {@link Model}. */ interface ModelParams { /** * The type name of the model. Used by {@link Fields."type"} to set a type attribute. */ name?: string; /** * Schema to use for mapping data between the model and table data. */ schema: Model.ModelSchema; /** * Table to used for reading and writing model data to dynamodb. */ table: Table; } /** * Model property value used for item updates. */ type ModelUpdateValue = Extract> | null; /** * Type for the Model schema which contains a Field for each Model property. */ type ModelSchema = { [key: string]: Fields.Field; }; /** * Model input type used in most Model methods. */ type ModelCore = { [key: string]: ModelType; }; /** * Model output type used in most Model methods. */ type ModelOut = { [key: string]: ModelType; }; /** * Model input type used for update Model methods. */ type ModelUpdate = { [key: string]: ModelUpdateValue; }; /** * Base output type for the Model read/write methods. */ interface BaseOutput { /** * Model item data read from the table. */ item: ModelOutT; /** * The result of the table read/write. */ result: RESULT; } /** * Return value of {@link Model.get}. */ interface GetOutput extends BaseOutput { } /** * Return value of {@link Model.create}, {@link Model.replace} and {@link Model.put}. */ interface PutOutput extends BaseOutput { } /** * Return value of {@link Model.delete}. */ interface DeleteOutput extends BaseOutput { } /** * Return value of {@link Model.update}. */ interface UpdateOutput extends BaseOutput { } /** * Type for the ModelT schema which contains a Field for each Model property. */ type ModelSchemaT = { [P in keyof Required]: Fields.Field; }; /** * Model input type used in most ModelT methods. */ type ModelCoreT = { [P in keyof T]: Exclude; }; /** * Model output type used in most ModelT methods. */ type ModelOutT = { [P in keyof T]: Exclude; }; /** * Model input type used for update Model methods. */ type ModelUpdateT = { [P in keyof Table.Optional]: ModelUpdateValue; } & KEY; /** * Params used when creating {@link ModelT}. * @param KEY - Key part of the model used for get and delete actions. * @param OUTPUT - The model output interface. */ interface ModelParamsT extends ModelParams { /** * Schema to use for mapping data between the model and table data. */ schema: ModelSchemaT; } /** * Generic version of Model, see {@link Model} for more details. * @param KEY - Key part of the model used for get and delete actions. * @param INPUT - The model input interface used for put and update. * @param OUTPUT - The model output interface. */ interface ModelT extends Model { /** * Schema to use for mapping data between the model and table data. */ schema: Model.ModelSchemaT; /** @inheritDoc {@inheritDoc (Model:class).toModel} */ toModel(data: Table.AttributeValuesMap): Model.ModelOutT; /** @inheritDoc {@inheritDoc (Model:class).toTable} */ toTable(data: Model.ModelCoreT): Model.TableData; /** @inheritDoc {@inheritDoc (Model:class).toTableUpdate} */ toTableUpdate(data: Model.ModelUpdateT): Model.TableUpdateData; /** @inheritDoc {@inheritDoc (Model:class).getParams} */ getParams(key: Model.ModelCoreT, options?: Table.GetOptions): DocumentClient.GetItemInput; /** @inheritDoc {@inheritDoc (Model:class).deleteParams} */ deleteParams(key: Model.ModelCoreT, options?: Table.DeleteOptions): DocumentClient.DeleteItemInput; /** @inheritDoc {@inheritDoc (Model:class).putParams} */ putParams(data: Model.ModelCoreT, options?: Table.PutOptions): DocumentClient.PutItemInput; /** @inheritDoc {@inheritDoc (Model:class).updateParams} */ updateParams(data: Model.ModelUpdateT, options?: Table.UpdateOptions): DocumentClient.UpdateItemInput; /** @inheritDoc {@inheritDoc (Model:class).get} */ get(key: Model.ModelCoreT, options?: Table.GetOptions): Promise>; /** @inheritDoc {@inheritDoc (Model:class).delete} */ delete(key: Model.ModelCoreT, options?: Table.DeleteOptions): Promise>; /** @inheritDoc {@inheritDoc (Model:class).create} */ create(data: Model.ModelCoreT, options?: Table.PutOptions): Promise>; /** @inheritDoc {@inheritDoc (Model:class).replace} */ replace(data: Model.ModelCoreT, options?: Table.PutOptions): Promise>; /** @inheritDoc {@inheritDoc (Model:class).put} */ put(data: Model.ModelCoreT, options?: Table.PutOptions): Promise>; /** @inheritDoc {@inheritDoc (Model:class).update} */ update(data: Model.ModelUpdateT, options?: Table.UpdateOptions): Promise>; /** @inheritDoc {@inheritDoc (Model:class).addBatchGet} */ addBatchGet(batchGet: Table.BatchGet, key: Model.ModelCoreT): Model.ModelResultT; /** @inheritDoc {@inheritDoc (Model:class).addBatchDelete} */ addBatchDelete(batchWrite: Table.BatchWrite, key: Model.ModelCoreT): Model.ModelResultT; /** @inheritDoc {@inheritDoc (Model:class).addBatchPut} */ addBatchPut(batchWrite: Table.BatchWrite, item: Model.ModelCoreT): Model.ModelResultT; /** @inheritDoc {@inheritDoc (Model:class).addTransactGet} */ addTransactGet(transactGet: Table.TransactGet, key: Model.ModelCoreT, itemAttributes?: string[]): Model.ModelResultT; /** @inheritDoc {@inheritDoc (Model:class).addTransactCheck} */ addTransactCheck(transactWrite: Table.TransactWrite, key: Model.ModelCoreT, conditions: Condition.Resolver[], returnFailure?: DocumentClient.ReturnValuesOnConditionCheckFailure): Model.ModelResultT; /** @inheritDoc {@inheritDoc (Model:class).addTransactDelete} */ addTransactDelete(transactWrite: Table.TransactWrite, key: Model.ModelCoreT, conditions?: Condition.Resolver[], returnFailure?: DocumentClient.ReturnValuesOnConditionCheckFailure): Model.ModelResultT; /** @inheritDoc {@inheritDoc (Model:class).addTransactPut} */ addTransactPut(transactWrite: Table.TransactWrite, item: Model.ModelCoreT, conditions?: Condition.Resolver[], returnFailure?: DocumentClient.ReturnValuesOnConditionCheckFailure): Model.ModelResultT; /** @inheritDoc {@inheritDoc (Model:class).addTransactUpdate} */ addTransactUpdate(transactWrite: Table.TransactWrite, item: Model.ModelUpdateT, conditions?: Condition.Resolver[], returnFailure?: DocumentClient.ReturnValue): Model.ModelResultT; } /** * See {@link Table.createTable} reasoning for having a createTable over support 'new TableT'. * @param KEY - Key part of the model used for get and delete actions. * @param INPUT - The model input interface used for put and update. * @param OUTPUT - The model output interface. * @param params - Options to used when creating Model. */ function createModel(params: ModelParamsT): Model.ModelT; /** * The object returned from model batch or transact methods that will get the * table item from the results and translate it to a model item. */ class ModelResult { private tableResult; private model; private key; private context; /** * @param tableResult - he batch or transact object to get the result from. * @param model - Model object used to convert the table item to a model item. * @param key - Key of the item to read or write to. * @param context - Context to pass to the Model.toModel method. */ constructor(tableResult: Table.TableResult, model: Model, key: Table.PrimaryKey.AttributeValuesMap, context: Fields.TableContext); /** * Get the model output value and the associated table item. * @returns The model and table item from the result. */ get(): { item: Model.ModelOut; tableItem: Table.AttributeValuesMap; } | void; } /** * Generic version of the {@link ModelResult} used by {@link ModelT} to allow typescript type validation. */ interface ModelResultT extends ModelResult { /** @inheritDoc {@inheritDoc (Model:namespace).ModelResult.get} */ get(): { item: Model.ModelOutT; tableItem: Table.AttributeValuesMap; } | void; } }