@stone-ton/aws-dynamodb-wrapper

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 @stone-ton/aws-dynamodb-wrapper

Alterando o endpoint do DynamoDB

Defina a variável de ambiente DYNAMO_CUSTOM_URL com a URL do seu endpoint personalizado.

DYNAMO_CUSTOM_URL = http://localhost:8000

Após definir a variável, a aplicação passará a se comunicar com o endpoint configurado (por exemplo, um servidor local do DynamoDB para desenvolvimento) em vez do endpoint padrão do DynamoDB.

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 '@stone-ton/aws-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 '@stone-ton/aws-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 '@stone-ton/aws-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 '@stone-ton/aws-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 '@stone-ton/aws-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 '@stone-ton/aws-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 '@stone-ton/aws-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 '@stone-ton/aws-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 '@stone-ton/aws-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',
      },
    ]
  }
])