cute-dynamo

Make DynamoDB cute with minimalism; worry about network costs later.

Features

• Fast development.
• Simple syntax.
• No pain.

Why

cute-dynamo solves a very fundamental problem with DynamoDB: and that is, development is slow...
With this design, we define rules that allow you to use DynamoDB across different projects without having custom code for each project.

Cute puts are minimalistic and are serialized JSON objects. This means you can define your data and everything in plain js code. No more writing DynamoDB relevant syntax and worrying about data types.
By design of DynamoDB, each item is limited to 400kb in size no matter how many attributes anyway.

There can't be cute without development speed.

Getting Started

Installation

npm install cute-dynamo

Usage

import { init, table } from 'cute-dynamo';

// Initialization 
//
// Depending on your application context (server-side or client-side), two ways for init:
// (FIRST WE SHOW THE PREFFERED WAY)
// .env variables: DYNAMODB_TABLE, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
 await init();
// ALTERNATIVE WAYS TO INIT
// Server-Side Initialization (using AWS Access Key ID and AWS Secret Access Key):
// IF YOU DONT WANT TO USE ENV VARS
 await init({
     region: 'us-east-1',
     accessKeyId: 'AKIAEXAMPLE',
     secretAccessKey: 'secret'
 });
 
// Initialize with Cognito Identity Pool ID for client-side usage
// IF YOU DONT WANT TO USE ENV VARS
 await init({
     region: 'us-east-1',
     identityPoolId: 'us-east-1:exampleId'
 });

// Putting Items into DynamoDB
// To store an item you can use put. This implemenation should transform the way you use put.
// You can deep nest anything and no setup. 
// This is the basic structure
await table().at().put();
// You can use plain js objects for your data because it gets serialized to a JSON
await table('tableName').at({'yourPKkeyName': 'PKvalue', 'yourSKname': 2711900504}).put({'comment': 'simple'});
await table('tableName').at({'yourPKkeyName': 'PKvalue', 'yourSKname': 2711900504}).put({'comments': ['comment1', 'comment2']});
 // YES YOU CAN NEST ANY LIST OR MAP AS COMPLICATED AS YOU LIKE
 // You can log the response as well.

// Getting Items from DynamoDB
// This is the basic structure
await table().at().get();
// Retrieving an item using both a primary key and a sort key:
 const item = await table('yourtablename').at({'yourPKkeyName': 'PKvalue', 'yourSKname': 1711900504}).get();
 console.log(item);
 
// Query 
table().at().query(count, descending)

const items = await table('yourtablename').at({ PK: 'CategoryA' }).query(10, true);
console.log(items);
// provide a start key for pagination
await table('yourtablename').at({ PK: 'User#123', SK: 123 }).query(2, false); // SK start key

// These examples cover the basic operations to get you started with cute-dynamo. 
// By following the minimalistic design principles of cute-dynamo, you 
// can ensure a consistent and simplified approach to working with DynamoDB across your projects.

FYI

DynamoDB Call	Estimated Time (ms)	Explanation
PK lookup in PK-only table	5 - 50	Direct GetItem access with only a PK. Fast and efficient.
PK lookup in PK-SK table	N/A	Direct lookup not possible without SK. Use Query instead.
PK and SK lookup in PK-SK table	5 - 50	Direct GetItem access with both PK and SK. Very fast and efficient for accessing a single item.
PK Query in PK-SK table (single item)	10 - 100	Query based on PK, fast if there's only one item for the PK.
PK Query in PK-SK table (multiple items)	20 - 200	Query based on PK, might take longer depending on the number of items returned.
Full Scan on any table (small table <1k items)	100 - 1000	Scans are slower and more resource-intensive, time increases with item size and count.
Full Scan on any table (large table >10k items)	1000 - 5000+	Significantly slower, highly dependent on table size, item size, and scan configuration.
Conditional Query on PK-SK table (filters)	20 - 200	Using Query with additional filters can increase time, depending on complexity and results size.