Biblioteca para integração com AWS DynamoDB utilizando o OpenTelemetry
npm install @stone-ton/aws-dynamodb-wrapperEsta 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.
Para instalar a biblioteca, use o seguinte comando:
``bash`
npm install @stone-ton/aws-dynamodb-wrapper
Defina a variável de ambiente DYNAMO_CUSTOM_URL com a URL do seu endpoint personalizado.
`shell`
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.
Aqui estão alguns exemplos de como usar as funções fornecidas pela biblioteca:
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.
`typescript
import { dynamodbGet } from '@stone-ton/aws-dynamodb-wrapper'
type User = {
pk: string,
sk: string,
name: string
}
const result = await dynamodbGet
Key: {
pk: 'USER#1',
sk: 'USER#1',
},
TableName: 'dynamodb-table'
})
console.log(result.name)
`
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.
`typescript
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
})
`
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.
`typescript
import { dynamodbUpdate } from '@stone-ton/aws-dynamodb-wrapper'
await dynamodbUpdate({
TableName: 'dynamodb-table',
Key: {
pk: 'USER#1',
sk: 'USER#1',
},
Update: {
name: 'Anya'
},
})
`
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.
`typescript
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
})
`
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.
`typescript
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'
}
]
}
})
`
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.
`typescript
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'
}
]
}
})
`
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.
`typescript
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',
},
}
}
])
`
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.
`typescript
import { dynamodbBatchGet } from '@stone-ton/aws-dynamodb-wrapper'
const result = await dynamodbBatchGet
TableName: 'dynamodb-table',
Keys: [
{
pk: 'USER#1',
sk: 'USER#1',
},
{
pk: 'USER#2',
sk: 'USER#2',
}
]
})
`
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.
`typescript
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',
},
]
}
])
``