limitless

README

Limitless

A thin wrapper around AWS DynamoDB. Uses AWS Go SDK V2.

Makes life easier and less verbose. Somewhat battle-tested. Removes need to manually Marshal/Unmarshall to/from AttributeValues. Uses the "dynamodb" tag for serialization and deserialization.

How to use:

import(
    "github.com/0Xero7/limitless"
    "github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/credentials"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb"
)

type User struct {
    UserId string `dynamodbav:"user_id"`
    Name   string `dynamodbav:"name,omitempty"`
}

func main() {
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        return err
    }
    limitlessClient := limitless.NewClient(dynamodb.NewFromConfig(cfg))

    // Scan
	results, lastEvaluatedKey, err := limitless.Scan[User](limitlessClient, ScanRequest{
		TableName: "users",
	})
}

Documentation

Index

• func BatchGetItem[T any](l *Limitless, tableName string, items []T) ([]T, error)
• func BatchPutItem[T any](l *Limitless, tableName string, items []T) error
• func DeleteItem[T any](l *Limitless, tableName string, key *T) error
• func GetItem[T any](l *Limitless, tableName string, key *T) (*T, error)
• func PutItem[T any](l *Limitless, tableName string, item T) error
• func PutItemConditional[T any](l *Limitless, tableName string, conditionExpression string, item T) error
• func Query[T any](l *Limitless, queryRequest QueryRequest) ([]T, map[string]types.AttributeValue, error)
• func Scan[T any](l *Limitless, request ScanRequest) ([]T, map[string]types.AttributeValue, error)
• func TransactWriteItems(l *Limitless, items *[]PutItemRequest, idempotencyToken *string) error
• func UpdateItem[T any](l *Limitless, tableName string, key *T, item *T) error
• type Limitless
  • func NewClient(dynamodb *dynamodb.Client) *Limitless
• type PutItemRequest
• type QueryRequest
• type ScanRequest

Functions

func BatchGetItem

func BatchGetItem[T any](l *Limitless, tableName string, items []T) ([]T, error)

func BatchPutItem

func BatchPutItem[T any](l *Limitless, tableName string, items []T) error

func DeleteItem

func DeleteItem[T any](l *Limitless, tableName string, key *T) error

DeleteItem deletes a single item from a DynamoDB table based on the provided key.

Parameters:

• l: A pointer to the Limitless client used to interact with DynamoDB.
• tableName: The name of the DynamoDB table from which to delete the item.
• key: A pointer to a struct of type T representing the primary key of the item to be deleted.

Returns:

• error: An error if the deletion operation fails, or nil if successful.

func GetItem

func GetItem[T any](l *Limitless, tableName string, key *T) (*T, error)

func PutItem

func PutItem[T any](l *Limitless, tableName string, item T) error

func PutItemConditional

func PutItemConditional[T any](l *Limitless, tableName string, conditionExpression string, item T) error

func Query

func Query[T any](l *Limitless, queryRequest QueryRequest) ([]T, map[string]types.AttributeValue, error)

Query performs a query operation on a DynamoDB table using the provided query request. It processes the condition and values, builds the necessary input for the DynamoDB Query API, executes the query, and unmarshals the results into a slice of type T.

Parameters:

• l: A pointer to the Limitless client.
• queryRequest: A QueryRequest struct containing the query parameters.

Returns:

• []T: A slice of type T containing the query results.
• map[string]types.AttributeValue: The LastEvaluatedKey from the query, which can be used for pagination.
• error: An error if the query operation fails, or nil if successful.

func Scan

func Scan[T any](l *Limitless, request ScanRequest) ([]T, map[string]types.AttributeValue, error)

Scan performs a scan operation on a DynamoDB table using the provided scan request. It retrieves items from the table or a secondary index, and unmarshals the results into a slice of type T.

Parameters:

• l: A pointer to the Limitless client.
• request: A ScanRequest struct containing the scan parameters.

Returns:

• []T: A slice of type T containing the scan results.
• map[string]types.AttributeValue: The LastEvaluatedKey from the scan, which can be used for pagination. Is nil if there are no items left to scan.
• error: An error if the scan operation fails, or nil if successful.

func TransactWriteItems

func TransactWriteItems(l *Limitless, items *[]PutItemRequest, idempotencyToken *string) error

func UpdateItem

func UpdateItem[T any](l *Limitless, tableName string, key *T, item *T) error

Types

type Limitless

type Limitless struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(dynamodb *dynamodb.Client) *Limitless

type PutItemRequest

type PutItemRequest struct {
	// TableName is the name of the DynamoDB table where the item will be put.
	TableName string

	// Item is the item to be put into the table. It should be a map or a struct
	// that can be marshaled into a DynamoDB-compatible format. Use the "dynamodbav" tag.
	Item interface{}
}

PutItemRequest represents the parameters for a DynamoDB PutItem operation.

type QueryRequest

type QueryRequest struct {
	// TableName is the name of the DynamoDB table to query.
	TableName string

	// Condition is the query condition expression. The condition expression has the format "#KEY operator :VALUE".
	// The "key" is inferred by removing the leading "#" in "#KEY". You provide the value of ":VALUE" in the [Values] field.
	// For example, "#name = :nameValue" would match items with the attribute "name" equal to the value provided in the "Values" map.
	Condition string

	// Values is a map of attribute names to attribute values, representing the query parameters.
	// For example, { ":nameValue": "Soumya" } would set the value of ":nameValue" equal to "Soumya".
	Values map[string]any

	// IndexName is an optional name of a secondary index to query instead of the base table.
	IndexName *string

	// ConsistentRead specifies whether to use strongly consistent reads. Must be false if using an index.
	// If set to true, the operation uses strongly consistent reads; otherwise, eventually consistent reads are used.
	ConsistentRead *bool

	// Ascending determines the order of the query results.
	// If set to true, the query processes items in ascending order; if false, in descending order.
	Ascending *bool

	// Limit sets the maximum number of items to evaluate (not necessarily the number of matching items).
	// If DynamoDB processes the number of items up to the limit while processing the results, it stops the operation and returns the matching values up to that point.
	Limit *int32

	// ProjectionExpression specifies the attributes to be returned in the query result.
	// This is a string identifying one or more attributes to retrieve from the table.
	ProjectionExpression *string

	// ExpressionAttributeNames provides name substitution for reserved words in the ProjectionExpression.
	// Use this if you need to specify reserved words as attribute names.
	ExpressionAttributeNames map[string]string

	// ExclusiveStartKey is the primary key of the item where the query operation will start.
	// Used for pagination to resume a query operation.
	ExclusiveStartKey map[string]types.AttributeValue
}

QueryRequest represents the parameters for a DynamoDB query operation.

type ScanRequest

type ScanRequest struct {
	// TableName is the name of the DynamoDB table to scan.
	TableName string

	// IndexName is an optional name of a secondary index to scan instead of the base table.
	IndexName *string

	// ConsistentRead specifies whether to use strongly consistent reads.
	// If set to true, the operation uses strongly consistent reads; otherwise, eventually consistent reads are used.
	ConsistentRead *bool

	// Limit sets the maximum number of items to evaluate (not necessarily the number of matching items).
	// If DynamoDB processes the number of items up to the limit while processing the results, it stops the operation and returns the matching values up to that point.
	Limit *int32

	// ExclusiveStartKey is the primary key of the item where the scan operation will start.
	// Used for pagination to resume a scan operation.
	ExclusiveStartKey map[string]types.AttributeValue
}

ScanRequest represents the parameters for a DynamoDB scan operation.