electrodb

What is electrodb?

ElectroDB is a DynamoDB library that simplifies the process of defining and interacting with DynamoDB tables. It provides a high-level abstraction for defining entities, managing relationships, and performing CRUD operations, making it easier to work with DynamoDB's complex data modeling and querying capabilities.

What are electrodb's main functionalities?

Entity Definition

This feature allows you to define an entity with its attributes and indexes. The code sample demonstrates how to create a User entity with attributes like userId, name, and email, and a primary index.

const { Entity } = require('electrodb');

const UserEntity = new Entity({
  model: {
    entity: 'User',
    version: '1',
    service: 'UserService'
  },
  attributes: {
    userId: { type: 'string', required: true },
    name: { type: 'string', required: true },
    email: { type: 'string', required: true }
  },
  indexes: {
    primary: {
      pk: { field: 'pk', composite: ['userId'] },
      sk: { field: 'sk', composite: [] }
    }
  }
});

CRUD Operations

This feature provides methods for performing CRUD operations on the defined entities. The code sample shows how to create, read, update, and delete a user entity.

const user = await UserEntity.put({
  userId: '123',
  name: 'John Doe',
  email: '[e-mail]'
}).go();

const fetchedUser = await UserEntity.get({ userId: '123' }).go();

const updatedUser = await UserEntity.update({ userId: '123' })
  .set({ name: 'Jane Doe' })
  .go();

const deletedUser = await UserEntity.delete({ userId: '123' }).go();

Querying

This feature allows you to perform complex queries on your entities. The code sample demonstrates how to query the User entity using the primary index.

const users = await UserEntity.query.primary({ userId: '123' }).go();

Relationships

This feature allows you to define and manage relationships between different entities. The code sample shows how to fetch a user along with their related orders using the Service class.

const { Service } = require('electrodb');

const UserService = new Service({
  User: UserEntity,
  Order: OrderEntity
});

const userWithOrders = await UserService.User.get({ userId: '123' }).include(OrderEntity).go();

Other packages similar to electrodb

dynamodb-toolbox

DynamoDB Toolbox is a set of tools that makes it easier to work with Amazon DynamoDB. It provides a simple and consistent way to define and interact with DynamoDB tables and items. Compared to ElectroDB, DynamoDB Toolbox offers a more lightweight and flexible approach but may require more manual setup for complex data models.

aws-sdk

The AWS SDK for JavaScript provides a comprehensive set of tools for interacting with AWS services, including DynamoDB. While it offers low-level access to DynamoDB's API, it lacks the high-level abstractions and convenience features provided by ElectroDB, making it more suitable for developers who need fine-grained control over their DynamoDB interactions.

dynogels

Dynogels is a DynamoDB data mapper for Node.js that simplifies the process of defining and interacting with DynamoDB tables. It offers a similar high-level abstraction as ElectroDB but is less actively maintained and may not support some of the latest DynamoDB features.

README

ElectroDB

ElectroDB is a DynamoDB library to ease the use of having multiple entities and complex hierarchical relationships in a single DynamoDB table.

Please submit issues/feedback or reach out on Twitter @tinkertamper.

---

New: Documentation now found at ElectroDB.dev

ElectroDB's new website for Documentation is now live at www.ElectroDB.dev.

---

Introducing: The NEW ElectroDB Playground

Try out and share ElectroDB Models, Services, and Single Table Design at electrodb.fun

---

Features

• Single-Table Entity Isolation - Entities created with ElectroDB will not conflict with other entities when using a single DynamoDB table.
• Attribute Schema Enforcement - Define a schema for your entities with enforced attribute validation, defaults, types, aliases, and more.
• Easily Compose Hierarchical Access Patterns - Plan and design hierarchical keys for your indexes to multiply your possible access patterns.
• Simplified Sort Key Condition Querying - Write efficient sort key queries by easily building compose keys.
• Simplified Filter Composition - Easily create complex readable filters for DynamoDB queries without worrying about the implementation of ExpressionAttributeNames, ExpressionAttributeValues, and FilterExpressions.
• Simplified Condition Composition - Use the same interface to casily create complex readable mutation conditions for DynamoDB queries without worrying about the implementation of ExpressionAttributeNames, ExpressionAttributeValues, and ConditionExpressions.
• Simplified Update Expression Composition - Easily compose type safe update operations without having to format tedious ExpressionAttributeNames, ExpressionAttributeValues, and UpdateExpressions.
• Easily Query Across Entities - Define "collections" to create powerful/idiomatic queries that return multiple entities in a single request.
• Automatic Index Selection - Use .find() or .match() methods to dynamically and efficiently query based on defined sort key structures.
• Simplified Pagination API - ElectroDB generates url safe cursors for pagination, allows for fine grain automated pagination, and supports async iteration.
• TypeScript Support - Strong TypeScript support for both Entities and Services now in Beta.
• Query Directly via the Terminal - Execute queries against your Entities, Services, Models directly from the command line.
• Stand Up Rest Server for Entities - Stand up a REST Server to interact with your Entities, Services, Models for easier prototyping.
• Use with your existing tables - ElectroDB simplifies building DocumentClient parameters, so you can use it with existing tables/data.

---

Turn this

tasks
  .patch({
    team: "core",
    task: "45-662",
    project: "backend",
  })
  .set({ status: "open" })
  .add({ points: 5 })
  .append({
    comments: [
      {
        user: "janet",
        body: "This seems half-baked.",
      },
    ],
  })
  .where(({ status }, { eq }) => eq(status, "in-progress"))
  .go();

Into This

{
  "UpdateExpression": "SET #status = :status_u0, #points = #points + :points_u0, #comments = list_append(#comments, :comments_u0), #updatedAt = :updatedAt_u0, #gsi1sk = :gsi1sk_u0",
  "ExpressionAttributeNames": {
    "#status": "status",
    "#points": "points",
    "#comments": "comments",
    "#updatedAt": "updatedAt",
    "#gsi1sk": "gsi1sk"
  },
  "ExpressionAttributeValues": {
    ":status0": "in-progress",
    ":status_u0": "open",
    ":points_u0": 5,
    ":comments_u0": [
      {
        "user": "janet",
        "body": "This seems half-baked."
      }
    ],
    ":updatedAt_u0": 1630977029015,
    ":gsi1sk_u0": "$assignments#tasks_1#status_open"
  },
  "TableName": "your_table_name",
  "Key": {
    "pk": "$taskapp#team_core",
    "sk": "$tasks_1#project_backend#task_45-662"
  },
  "ConditionExpression": "attribute_exists(pk) AND attribute_exists(sk) AND #status = :status0"
}

Changelog

[2.12.0] - 2023-11-27

Added

• Adds support for nested usage of any and CustomAttributeType attribute types. Prior to this release, any and CustomAttributeType could only be used with root attributes. This change adds support for CustomAttributeType to be used with map attributes.
• Adds new condition property on index definitions to prevent unnecessary GSI writes & hot partitions for certain data models. The provided condition callback will be invoked at query-time, passed all attributes set on that mutation, and if it returns false the index will not be written to your DynamoDB table. Addresses Issue #330.