ElectroDB

A Service in ElectroDB represents a collection of related Entity objects. While you can use Entities independently, you must use a Service if you intend to perform queries that "join" multiple Entities. Services allow multiple Entities to coexist on a single DynamoDB table without collision.

When you define a Service, the property names you assign to the entities become the "aliases" used to reference them through the Service instance.

import { Service } from "electrodb";

// The property names 'employee' and 'task' become the aliases
const TaskApp = new Service(
  {
    employee: Employee, // accessible via TaskApp.entities.employee
    task: Task,        // accessible via TaskApp.entities.task
  },
  { table, client },
);

You can update nested properties in complex DynamoDB types using dot notation or square brackets.

Using Chain Methods

To target a specific property in a map or an index in a list, use the JSON path as the attribute name:

• Map property: Use dot notation (e.g., set({ 'address.city': 'New York' })).
• List element: Use square brackets with the index (e.g., remove(['items[0]'])).

Using the data() method

The data() method provides TypeScript type safety for complex types. Instead of using string paths, you can drill into the attributes object directly:

// Example: Updating a nested property in a map via data()
entity.update({ id: '123' }).data(({ attributes, operations }) => {
  operations.set(attributes.metadata.location, 'London');
}).go();

ElectroDB supports using the where() method with DynamoDB's complex attribute types like map and list. When using the injected attributes object, you can drill into the attribute to apply filters directly to nested elements.

• Maps: Access nested keys directly via the attribute object.
• Lists: Access specific elements or indices within the list.

// Example: Filtering on a map attribute
await MyEntity.get({ id: '1' })
  .where(({ metadata }) => eq(metadata.color, 'red'))
  .go();

// Example: Filtering on a list element
await MyEntity.get({ id: '1' })
  .where(({ tags }) => contains(tags, 'important'))
  .go();

All ElectroDB query chains must be terminated with either .go() or .params() to perform an action. Both methods accept an optional configuration object for execution options.

.params()

Terminates the chain synchronously and returns a formatted object ready to be passed directly to the DynamoDB docClient.

.go()

Terminates the chain asynchronously and executes the query against DynamoDB using the client provided in the model or via the execution options. It returns a Promise that resolves to an object containing the data and an optional cursor.

Return shape for .go():

{
  data: Array<T>,
  cursor: string | null
}

Live documentation examples in the ElectroDB docs are organized into self-contained directories. Each example follows a specific file structure to ensure type safety and modularity:

• example.ts: The primary code shown in the documentation. It imports the Entity from ./entity.
• entity.ts: Contains the Entity instantiation, importing the table name from ./table.
• table.ts: Defines the DynamoDB table and exports the table name.

This structure allows examples to modify their own schema (entity.ts) or table definition (table.ts) without affecting other documentation pages.

src/examples/<example-name>/
  example.ts   # the code shown by default; imports the entity from ./entity
  entity.ts    # the Entity instantiation; imports the table name from ./table
  table.ts     # the DynamoDB table definition + exported table name

By default, if a condition expression fails during a mutation, ElectroDB throws an error. You can change this behavior using the returnOnConditionCheckFailure option:

• Set to true: The method will return { rejected: true } instead of throwing.
• Set to "all_old": The method will return { rejected: true } and also include the existing item under the data property.

// Example: Returning a rejected status instead of throwing
const result = await myEntity.put({ id: '123' }, { version: 1 }).go({
  returnOnConditionCheckFailure: true
});

if (result.rejected) {
  // Handle the fact that the condition failed
}

In DynamoDB, standard update operations create a new item by default if the target record does not exist. This can lead to partial items and incorrect typing.

ElectroDB's patch method prevents this by dynamically utilizing the attribute_exists() parameter. This ensures that an update only occurs if the record already exists, making it a "safer" update operation.

Key Difference: Unlike the update method, patch returns an EntityItem type rather than just identifiers, because it guarantees you are interacting with an existing, fully-typed record.

// Note: The specific method call is not in this segment, but the concept is:
// patch() ensures attribute_exists() is applied to prevent accidental creation.