The Transformation class provides an easy way to transform items in a DynamoDB table. It allows you to add, remove, rename, and modify attributes on items, as well as filter and remove items from the table.

To create a transformation use the create-transformation command:

npx dynormo create-transformation <name>

This will create a new file in the transformations directory with the following contents:

import { Transformation, TransformationInterface } from 'dynormo'
import { DynormoClient } from '.dynormo'

// TODO: Add the entity types affected in this transformation here (e.g. Entity1 | Entity2)
type ItemTypes = any; 

class TestTransformation implements TransformationInterface<ItemTypes> {
    table = '<<TABLE_NAME>>';
    client = new DynormoClient({}).rawClient; // TODO: Add your DynamoDBClient here

    public async transform(): Promise<Transformation<ItemTypes>> {
        return new Transformation<ItemTypes>(this.table, this.client);
        // TODO: Add transformation here
        // e.g. .addAttribute('newAttribute', (item: ItemTypes) => {
        //          return 'string'
        //      })
    }

    public async rollback(): Promise<Transformation<ItemTypes>> {
        return new Transformation<ItemTypes>(this.table, this.client);
        // TODO: Add transformation that revert the changes made in transform() here
        // e.g. .removeAttribute('newAttribute')
    }

    public async backup(name: string): Promise<void> {
        new Transformation<ItemTypes>(this.table, this.client).backup(name);
    }
}

export default TestTransformation;

Fill in the table and client properties with the name of the table and an instance of the DynamoDBClient class from the @aws-sdk/client-dynamodb package. You can also use the DynormoClient.rawClient to get the underlying DynamoDBClient instance.

Then add the transformation logic to the transform() method. This method should return a Transformation object that contains the transformation logic. You can use the rollback() method to revert the changes made in the transform() method. The backup() method should be used to create a backup of the table before transforming it.

To run a transformation use the run-transformation command:

npx dynormo run-transformation <name>

This will ask you if you want to perform a backup before transforming the table. If you choose to perform a backup, it will ask you for the name of the backup. Keep in mind this command depending on the size of the table, it may take a while to complete.

To preview a transformation use the preview-transformation command:

npx dynormo preview-transformation <name>

This will ask you for the name of the file to store the preview in. It will then show you the items that will be transformed. Without actually transforming the table.

To rollback a transformation use the rollback-transformation command:

npx dynormo rollback-transformation <name>

This will ask you if you want to perform a backup before rolling back the transformation. Keep in mind this might not be able to restore all the items that were removed by the transformation. Restoring from a backup is the safest way to rollback a transformation.

Creates a new Transformation object.

• table - The name of the DynamoDB table to transform.
• client - An instance of the DynamoDBClient class from the @aws-sdk/client-dynamodb package. You can also use the DynormoClient.rawClient to get the underlying DynamoDBClient instance.

Adds an attribute to the item. If the attribute already exists, it will be overwritten.

• attribute - The name of the attribute to add.
• value - A function that returns the value of the attribute.

The Transformation object.

Removes an attribute from the item.

• attribute - The name of the attribute to remove.

The Transformation object.

Renames an attribute on the item.

• oldName - The current name of the attribute.
• newName - The new name of the attribute.

The Transformation object.

Modifies an attribute on the item.

• attribute - The name of the attribute to modify.
• value - A function that returns the new value of the attribute.

The Transformation object.

Sets the value of an attribute on the item to a static value.

• attribute - The name of the attribute to set.
• value - The value to set the attribute to.

The Transformation object.

Filters items that should not be transformed.

• filter - A function that returns true if the item should be transformed.

The Transformation object.

Maps an item to a new item.

• map - A function that returns the new item.

The Transformation object.

Removes an item from the table.

• filter - A function that returns true if the item should be removed.

The Transformation object.

Backs up the table before transforming it.

• name - The name of the backup.

A promise that resolves when the backup is complete.

Transforms the items in the table.

A promise that resolves when the transformation is complete.

Preview the items that will be transformed and store them in a file.

• filename - The name of the file to store the items in.

A promise that resolves when the preview is complete.

Here are some examples of how to use the Transformation class:

import { DynormoClient, FindOne1Entity } from '.dynormo';
import { Transformation, TransformationInterface } from 'dynormo';

type ItemTypes = FindOne1Entity;

class ExampleTransformation implements TransformationInterface<ItemTypes> {
    table = 'your-table-name';
    client = new DynormoClient({}).rawClient;

    public async transform(): Promise<Transformation<ItemTypes>> {
        return new Transformation<ItemTypes>(this.table, this.client)
            .addAttribute('combinedAttr', (item: ItemTypes) => {
                return `${item.stringAttr1} ${item.stringAttr2}`;
            })
            .filter((item: ItemTypes) => {
                return item.stringAttr1 !== 'test';
            })
            .renameAttribute('stringAttr1', 'newStringAttr1');
    }

    public async rollback(): Promise<Transformation<ItemTypes>> {
        return new Transformation<ItemTypes>(this.table, this.client)
            .renameAttribute('newStringAttr1', 'stringAttr1')
            .removeAttribute('combinedAttr');
    }

    public async backup(name: string): Promise<void> {
        new Transformation<ItemTypes>(this.table, this.client).backup(name);
    }
}

export default ExampleTransformation;