Dynamoco + Mocoquery

Like a Carebear giving DynamoDB a hug

Project Documentation »

API Documentation »

Report Bug

Request Feature

Dynamoco + Mocoquery

Overview

DynamoDB is a datastore that allows you to not manage as many details as a regular database. You just give it data; it faithfully holds it, and pretty quickly gives it back to you when you ask for it. Sound geat, right?!?! It's almost great. DynamoDB is a solid product from AWS, but the way you interact with it feels like shoving your finger in your eye.

Enter: Dynamoco!

A small but mighty, wrapper that is strong enough to get what you want out of DynamoDB, and it's gentle enough to help you feel like you are bowling with bumpers up. #NoGutters

Writeen in Typescript, it helps you auto-complete your way to valid queries, and other ways to pull your data out. It also helps you with type-check compiling and all that jazz if you are into that. If not its super easy to add it as regular ol' javascript yall.

The Dynamoco Problem

The API of DynamoDB has a steep learning curve.
The flexibiltiy in the DynamoDB Client creates too much complexity to comprehend when you are just getting started.
Dynamoco optimizes for a few normative use-cases, and it makes those very easy.
If you need to do the more complicated parts, it attempts to move out of the way.

The Dynamoco Solution

Use this package if:

You need to just get going with DynamoDB
You find the DynamoDB API difficult or at least optimzed for AWS engineers and not you.
Streamlined and flexible modules are your kind of your thing.
its like getting dynamo-converter, and dynamo-client and dynamo-plus all for the price of one.

Installation

npm install @federalies/dynamoco
# or
yarn add @federalies/dynamoco

Usage

First, know that this package is the ultimate BOGO or Two-For-One. Yes friends,there are in fact two, count them, two independent functions that work nicely together in the dynamoco module. Both come tested and documented free to you. What a time to be alive!

The first function is the gentle wrapper and the module namesake. (dynamoco)

But wait there's more, for free, you get a second and not to be overlooked, incredibly pleasant query builder - mocoquery

Together this dynamic duo cover ground on the API exposed by DynamoDB.

Using Get Item

import {DynamoDB} from 'aws-sdk'
import {dynamoco} from '@federalies/dynamoco'  // yay for tree-shaking
import {credentials} from './credentials'

;(async ()=>{
    const d = new DynamoDB({credentials})
    const moco = dynamoco(d)
    // using a table that is already available
    const resutls = await moco.getItem('MyTable', {MyKey: 'SomeValue'})
    console.log(results._Item) 
        /* {    
                MyKey: 'SomeValue', 
                numberValues: 1,
                stringValues: 'strings are strings'
            } 
        */
})()

Using The MocoQuery Builder

import {DynamoDB} from 'aws-sdk'
import {mocoquery, dynamoco} from '@federalies/dynamoco'
import {credentials} from './credentials'

;(async ()=>{
    const d = new DynamoDB({credentials})
    const queryParams = mocoquery('MyTable')
                        .select('*')
                        .where(['Year','<=',2020])
                        .extract()

    // using the regular DynamoDB Client 
    const regularResults = await d.query(queryParams)
    console.log('regularResults', regularResults.Items)

    // using the regular DynamoDB Client 
    const ezResults = await dynamoco(d).query(queryParams)
    console.log('ezResults', ezResults._Items)
})()

For more examples, please refer to the Documentation

Technical

Single dependency

By design, this module has a single, external, run-time dependency (aws-sdk). It uses a few other packages with tests, and some built-in modules to node. It is a stated goal of the project to keep the dependencies as small as reasonable. (NOTE: that is not equivalent to "as small as possible")

Dependencies

aws-sdk

Codebase

This is a Typescript codebase, and aims to be relatively up to date with the latest version. Adopting typescript versions updates will likely comence after a version hardening period in the wild, but might be hastened if a new language feature has been added that substantially supports this project.

Roadmap

See the open issues for a list of proposed features (and known issues).

Wait, But WHY?

But hey Eric, didn't you see any of :

Quite simply... Nope. Nope. Nope.

I did not. This project was made in anger after dealing with the regular documentation for Dynamo that NEVER even mentions there is an easier way. Not once... Not until had dug to the bottom of thier docs, did I discover that the Document API and higher level API exist.

Lesson(s) Learned:

Importance of Reading The Docs
How to Publish an NPM module :P ( thanks np )
Github Pages
Github Actions
lots more

Would I recommend anyone use this module - I tihnk so :shrug:

Community

Coming soon:

Community Chat
Stack Overflow hashtags
And Other Supporting Documentation

See the Community Standards and Code of Conduct

Contact

Eric D Moore

Contributing

Have a question? Ask your question inside an issue! We'd love to hear from you.

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

Contributors

Made with :heart: by @ericdmoore and maybe you?

use the emoji legend

_{Eric D Moore}
💬 ✅ 📖 💻 ⚠️ 🎨 💡

This project follows the all-contributors specification. Contributions of any kind welcome!

Acknowledgements & Credits

Care Bear Picture Logo
standard-readme

License

Distributed under the MIT License. See LICENSE for more information.