AWS DynamoDB Wrapper

Esta biblioteca facilita o uso do Amazon DynamoDB, fornecendo funções convenientes para operações comuns, como leitura, gravação, exclusão, consulta e escaneamento. Além disso, a lib oferece funções com sufixo Raw, as quais recebem e respondem exatamente da mesma forma que a biblioteca padrão da AWS, proporcionando maior flexibilidade e compatibilidade com códigos existentes desenvolvidos para a AWS.

Instalação

Para instalar a biblioteca, use o seguinte comando:

npm install @fintalk.ai/dynamodb-wrapper

Exemplos de Uso

Aqui estão alguns exemplos de como usar as funções fornecidas pela biblioteca:

dynamodbGet

A função dynamodbGet foi desenvolvida para simplificar as operações de leitura no Amazon DynamoDB, permitindo a recuperação de um item específico com base em sua chave (PK e SK). Para aprimorar ainda mais a flexibilidade e a clareza do código, incorporamos o conceito de tipagem genérica, possibilitando que o resultado retornado seja automaticamente tipado de acordo com o formato esperado.

import { dynamodbGet } from '@fintalk.ai/dynamodb-wrapper'

type User = {
  pk: string,
  sk: string,
  name: string
}

const result = await dynamodbGet<User>({
  Key: {
    pk: 'USER#1',
    sk: 'USER#1',
  },
  TableName: 'dynamodb-table'
})

console.log(result.name)

dynamodbPut

A função dynamodbPut foi projetada para simplificar as operações de escrita no Amazon DynamoDB, possibilitando a inserção de um item na tabela. Uma característica adicional foi incorporada para oferecer maior controle sobre as operações de escrita: o parâmetro opcional ForcePut. Quando este parâmetro é definido como true, a função realiza a operação PUT, sobrescrevendo qualquer item existente com a mesma chave (PK e SK).

Ao utilizar a função dynamodbPut, é essencial fornecer corretamente o parâmetro Key, contendo as informações da chave (PK e SK) da tabela, e o parâmetro Item, contendo os dados do item a ser inserido ou atualizado.

import { dynamodbPut } from '@fintalk.ai/dynamodb-wrapper'

await dynamodbPut({
  TableName: 'dynamodb-table',
  Key: {
    pk: 'USER#1',
    sk: 'USER#1',
  },
  Item: {
    name: 'Bond'
  },
})

// Força sobrescrita do item. Não mantém dados antigos caso exista.
await dynamodbPut({
  TableName: 'dynamodb-table',
  Key: {
    pk: 'USER#1',
    sk: 'USER#1',
  },
  Item: {
    name: 'Bond'
  },
  ForcePut: false
})

dynamodbUpdate

A função dynamodbUpdate foi projetada para simplificar operações de atualização de um item no Amazon DynamoDB, proporcionando uma interface fácil de usar. Ao utilizar esta função, é necessário fornecer o parâmetro Key, contendo as chaves (PK e SK) do item a ser atualizado, e o parâmetro Update, contendo os dados que serão modificados no item existente.

É importante destacar que, por questões de simplicidade, esta função não suporta a atualização de campos aninhados nem operações de delete ou add de objetos dentro do item. Caso seja necessário o suporte para operações em objetos aninhados ou outras atualizações mais avançadas, recomenda-se a utilização da função dynamodbUpdateRaw.

import { dynamodbUpdate } from '@fintalk.ai/dynamodb-wrapper'

await dynamodbUpdate({
  TableName: 'dynamodb-table',
  Key: {
    pk: 'USER#1',
    sk: 'USER#1',
  },
  Update: {
    name: 'Anya'
  },
})

dynamodbDelete

A função dynamodbDelete foi projetada para facilitar operações de exclusão de itens em uma tabela do Amazon DynamoDB. Para aprimorar o controle sobre essas operações, introduzimos o parâmetro opcional CheckExists. Quando esse parâmetro é configurado como true, a função verifica a existência do item antes de tentar deletá-lo. Se o item não existir e CheckExists estiver ativado, a função lançará um erro indicando a tentativa de exclusão de um item inexistente.

import { dynamodbDelete } from '@fintalk.ai/dynamodb-wrapper'

await dynamodbDelete({
  TableName: 'dynamodb-table',
  Key: {
    pk: 'USER#1',
    sk: 'USER#1',
  },
})

// Força um throw de condition caso o item não exista
await dynamodbDelete({
  TableName: 'dynamodb-table',
  Key: {
    pk: 'USER#1',
    sk: 'USER#1',
  },
  CheckExists: true
})

dynamodbQuery

A função dynamodbQuery foi desenvolvida para simplificar consultas no Amazon DynamoDB, permitindo a recuperação de dados específicos com base na chave (PK). Ao utilizar esta função, é necessário fornecer o parâmetro PrimaryKey, contendo os valores das chaves primárias a serem utilizados na consulta. Além disso, é possível refinar a busca utilizando o parâmetro opcional SortKeyCondition, que permite a definição de condições para a chave de classificação (Sort Key). Adicionalmente, o parâmetro FilterConditions possibilita a aplicação de filtros adicionais sobre os atributos dos itens retornados.

A função também suporta paginação para facilitar a recuperação de grandes conjuntos de resultados. O parâmetro StartKeyEncoded é utilizado para continuar a busca a partir de onde a consulta anterior foi interrompida, sendo essencial que o valor retornado como LastKeyEncoded na consulta anterior seja passado como StartKeyEncoded para a próxima página. O parâmetro Limit pode ser empregado para definir o número máximo de itens a serem retornados.

Para utilizar um índice GSI (Global Secondary Index), você pode especificar o nome do índice no parâmetro IndexName.

import { dynamodbQuery } from '@fintalk.ai/dynamodb-wrapper'

const result = await dynamodbQuery({
  TableName: 'dynamodb-table',
  PrimaryKey: {
    Key: 'pk',
    Value: 'USER#1'
  }
})

// Query com operações com a SK
const result = await dynamodbQuery({
  TableName: 'dynamodb-table',
  IndexName: 'gsi-index',
  PrimaryKey: {
    Key: 'pk',
    Value: 'USER#1'
  },
  SortKeyCondition: {
    ComparisonOperator: 'BEGINS_WITH',
    Key: 'sk',
    Value: 'PRODUCT'
  }
})

// Query com paginação
const result = await dynamodbQuery({
  TableName: 'dynamodb-table',
  PrimaryKey: {
    Key: 'pk',
    Value: 'USER#1'
  },
  StartKeyEncoded: 'LastKeyEncoded-anterior',
  Limit: 10
})

// Query com operações de filter
const result = await dynamodbQuery({
  TableName: 'dynamodb-table',
  PrimaryKey: {
    Key: 'pk',
    Value: 'USER#1'
  },
  FilterConditions: {
    Type: 'COMPARISON',
    ComparisonOperator: 'EQ',
    Key: 'name',
    'Value': 'Anya'
  }
})

const result = await dynamodbQuery({
  TableName: 'dynamodb-table',
  PrimaryKey: {
    Key: 'pk',
    Value: 'USER#1'
  },
  FilterConditions: {
    Type: 'CONDITIONAL',
    Operator: 'AND',
    Conditions: [
      {
        Type: 'COMPARISON',
        ComparisonOperator: 'EQ',
        Key: 'name',
        Value: 'Anya'
      },
      {
        Type: 'COMPARISON',
        ComparisonOperator: 'BEGINS_WITH',
        Key: 'gsi',
        Value: 'PRODUCT'
      }
    ]
  }
})

dynamodbScan

A função dynamodbScan foi projetada para simplificar operações de varredura (scan) no Amazon DynamoDB, permitindo a recuperação de dados em toda a tabela ou em um índice específico. Ao utilizar esta função, é possível opcionalmente fornecer o parâmetro IndexName, permitindo a varredura de um índice global secundário (GSI - Global Secondary Index). Além disso, a função suporta a paginação, onde o parâmetro StartKeyEncoded é utilizado para continuar a varredura a partir de onde a consulta anterior foi interrompida. É crucial observar que o valor fornecido para StartKeyEncoded deve ser o resultado retornado como LastKeyEncoded na consulta anterior.

import { dynamodbScan } from '@fintalk.ai/dynamodb-wrapper'

const result = await dynamodbScan({
  TableName: 'dynamodb-table',
  IndexName: 'gsi-index',
  StartKeyEncoded: 'LastKeyEncoded-anterior',
  Limit: 10
})

// Scan com operações de filter
const result = await dynamodbScan({
  TableName: 'dynamodb-table',
  FilterConditions: {
    Type:'CONDITIONAL',
    Operator: 'AND',
    Conditions: [
      {
        Type: 'COMPARISON',
        ComparisonOperator: 'EQ',
        Key: 'name',
        Value: 'Anya'
      },
      {
        Type: 'COMPARISON',
        ComparisonOperator: 'BEGINS_WITH',
        Key: 'gsi',
        Value: 'PRODUCT'
      }
    ]
  }
})

dynamodbTransactWrite

A função dynamodbTransactWrite foi concebida para facilitar operações de gravação atômicas e transacionais no Amazon DynamoDB. Esta função permite a execução de operações de atualização (Update), inserção (Put) e exclusão (Delete) em várias tabelas, garantindo a consistência dos dados e mantendo a integridade das transações.

É vital ressaltar que, ao empregar a função dynamodbTransactWrite, esta garante que as chaves primárias (PK) e secundárias (SK) não sejam duplicadas dentro da mesma tabela durante a transação. Ademais, é crucial salientar que o uso da função dynamodbTransactWrite está sujeito a um limite no número de transações que podem ser executadas em uma única chamada.

import { dynamodbTransactWrite } from '@fintalk.ai/dynamodb-wrapper'

await dynamodbTransactWrite([
  {
    Update: {
      TableName: 'dynamodb-table',
      Key: {
        pk: 'USER#1',
        sk: 'USER#1',
      },
      Update: {
        name: 'Bond'
      },
    }
  },
  {
    Put: {
      TableName: 'dynamodb-table',
      Key: {
        pk: 'USER#2',
        sk: 'USER#2',
      },
      Item: {
        name: 'Yor'
      },
    }
  },
  {
    Delete: {
      TableName: 'dynamodb-table',
      Key: {
        pk: 'USER#3',
        sk: 'USER#3',
      },
    }
  }
])

dynamodbBatchGet

Ao contrário da biblioteca padrão da AWS para o Amazon DynamoDB, é importante notar que o método dynamodbBatchGet apenas operações de leitura de uma tabela por vez. Essa escolha foi feita com o intuito de manter a interface simples e direta, priorizando a facilidade de uso para operações de lote. Caso deseje realizar operações de leitura em várias tabelas simultaneamente, recomenda-se o uso da função dynamodbBatchGetRaw.

import { dynamodbBatchGet } from '@fintalk.ai/dynamodb-wrapper'

const result = await dynamodbBatchGet<User>({
  TableName: 'dynamodb-table',
  Keys: [
    {
      pk: 'USER#1',
      sk: 'USER#1',
    },
    {
      pk: 'USER#2',
      sk: 'USER#2',
    }
  ]
})

dynamodbBatchWrite

A função dynamodbBatchWrite foi desenvolvida para simplificar e agilizar operações de escrita em várias tabelas no Amazon DynamoDB. Essa função permite a realização de múltiplas operações PUT e DELETE em lotes, otimizando a eficiência no gerenciamento de dados distribuídos em diferentes tabelas. Ao utilizar a função dynamodbBatchWrite para realizar operações PUT e DELETE em várias tabelas, é crucial assegurar que as chaves (PK e SK) não sejam duplicadas.

Cada operação PUT ou DELETE dentro do lote é tratada individualmente, e não há uma garantia automática de que todas as operações serão bem-sucedidas ou falharão em conjunto. Caso já exista um item com a mesma chave primária que está sendo inserida, o DynamoDB realizará uma substituição do item existente pelos novos dados fornecidos na operação PUT.

import { dynamodbBatchWrite } from '@fintalk.ai/dynamodb-wrapper'

await dynamodbBatchWrite([
  {
    TableName: 'dynamodb-table',
    PutItems: [
      {
        pk: 'USER#1',
        sk: 'USER#1',
        name: 'Anya',
      },
      {
        pk: 'USER#2',
        sk: 'USER#2',
        name: 'Yor',
      },
    ],
    DeleteKeys: [
      {
        pk: 'USER#3',
        sk: 'USER#3',
      },
    ]
  },
  {
    TableName: 'dynamodb-table-sdx',
    DeleteKeys: [
      {
        pk: 'USER#4',
        sk: 'USER#4',
      },
    ]
  }
])