@netizen-experience/aws-sdk-helpers

AWS SDK Helpers

This library provides helper functions to interact with AWS S3 and DynamoDB, making it easier to perform common operations in S3 and DynamoDB.

Table of Contents

• Installation
• Usage and Examples
  • Database (DynamoDB)
    • Creating an Item
    • Getting an Item
    • Updating an Item
    • Deleting an Item
    • Querying Items
    • Querying Items by Prefix
    • Batch Writing Items
    • Error Handling
    • Utilities
  • Storage (S3)
    • Uploading an Object
    • Getting an Object
    • Deleting an Object
    • Checking if an Object Exists
    • Creating a Pre-Signed URL for Download
    • Creating a Pre-Signed URL for Upload

Installation

To install this library, run:

npm install @netizen-experience/aws

Usage and Examples

Initialize AWS clients before using the library functions.

const { dynamo, s3 } = getAwsClients();

Database (DynamoDB)

Define DynamoDB tables with name, primary key, secondary search indexes (if any).

const table = defineTable(dynamo, {
  name: "SOME_TABLE_NAME",
  primaryKey: { partitionKey: "pk", sortKey: "sk" },
  secondaryIndex: {
    firstGSI: { partitionKey: "pk2", sortKey: "sk2" },
    secondLSI: { partitionKey: "pk", sortKey: "sk3" },
  },
});

Creating an Item

await table.create({
  schema: z.object({ partitionKey: z.string(), sortKey: z.string(), data: z.string() }),
  item: { partitionKey: "pk", sortKey: "sk", data: "example" },
});

Getting an Item

const item = await table.get({
  schema: z.object({ partitionKey: z.string(), sortKey: z.string(), data: z.string() }),
  key: { partitionKey: "pk", sortKey: "sk" },
});

Updating an Item

await table.update({
  schema: z.object({ partitionKey: z.string(), sortKey: z.string(), data: z.string().optional() }),
  attributes: { partitionKey: "pk", sortKey: "sk", data: "updated data" },
});

Deleting an Item

await table.remove({
  key: { partitionKey: "pk", sortKey: "sk" },
});

Querying Items

const items = await table.query({
  schema: z.object({ partitionKey: z.string(), sortKey: z.string(), data: z.string() }),
  attributes: { partitionKey: "pk" },
});

Querying Items by Prefix

const items = await table.queryByPrefix({
  schema: z.object({ partitionKey: z.string(), sortKey: z.string(), data: z.string() }),
  attributes: { partitionKey: "pk", sortKey: "prefix" },
});

Batch Writing Items

await table.batchWrite({
  items: [
    {
      type: "put",
      schema: z.object({ partitionKey: z.string(), sortKey: z.string(), data: z.string() }),
      data: { partitionKey: "pk1", sortKey: "sk1", data: "example1" },
    },
    {
      type: "delete",
      key: { partitionKey: "pk2", sortKey: "sk2" },
    },
  ],
});

Error Handling

All functions throw a DynamoError in case of an error. You can catch and handle these errors as follows:

import { DynamoError } from "./lib/database/errors";

try {
  await table.create({
    schema: z.object({ partitionKey: z.string(), sortKey: z.string(), data: z.string() }),
    item: { partitionKey: "pk", sortKey: "sk", data: "example" },
  });
} catch (error) {
  if (error instanceof DynamoError) {
    console.error("DynamoDB Error:", error.message);
  } else {
    console.error("Unexpected Error:", error);
  }
}

Utilities

This library also provides utility functions to help in generating and parsing prefixed keys.

import { generatePrefixedKey, parsePrefixedKey } from "@netizen-experience/aws";

const prefixedKey = generatePrefixedKey("prefix", "key");
console.log(prefixedKey); // Output: "prefix#key"

const { prefix, key } = parsePrefixedKey("prefix#key");
console.log(prefix); // Output: "prefix"
console.log(key); // Output: "key"

Storage (S3)

Define an S3 bucket with the client and bucket name.

const bucket = defineBucket(s3, "your-bucket-name");

Uploading an Object

await bucket.upload({
  key: "path/to/your/object",
  body: "Your object content",
});

Getting an Object

const object = await bucket.get({
  key: "path/to/your/object",
});

Deleting an Object

await bucket.delete({
  key: "path/to/your/object",
});

Checking if an Object Exists

const head = await bucket.headObject({
  key: "path/to/your/object",
});

Creating a Pre-Signed URL for Download

const url = await bucket.createPreSignedUrl({
  key: "path/to/your/object",
  expiresIn: 3600, // Optional, default is 3600 seconds
});

Creating a Pre-Signed URL for Upload

const uploadUrl = await bucket.createUploadUrl({
  key: "path/to/your/object",
  expiresIn: 1200, // Optional, default is 3600 seconds
});