Required dependencies

npm install @aws-sdk/lib-dynamodb @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb jsonschema

No native build steps, pod installs, or Expo prebuild steps are required. This is a pure Node.js library.

Project setup

1. Copy the source/ directory into your project, e.g. src/lib/electrodb/.
2. In your entry point, require or import directly from the copied files:

   import { Entity } from "./lib/electrodb/entity";
   import { Service } from "./lib/electrodb/service";
   

3. If using TypeScript, ensure "moduleResolution": "node" and "esModuleInterop": true in tsconfig.json. The source uses CommonJS (require), so set "module": "commonjs" or use a bundler that handles CJS interop.
4. Create and configure a DynamoDB DocumentClient from the AWS SDK v3:

   import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
   import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
   
   const dynamo = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }));
   

5. Pass the client and table name into each Entity or Service constructor via the config object.
6. Optionally set AWS_REGION and credential env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) or use an IAM role; ElectroDB does not manage credentials itself.

Public API

Entity

class Entity {
  constructor(model: object, config?: { client?: DynamoDBDocumentClient; table?: string; listeners?: Function[]; logger?: Function });
  get(key: object): ChainState;
  put(item: object): ChainState;
  update(key: object): ChainState;
  delete(key: object): ChainState;
  query: Record<string, (composite: object) => ChainState>;
  scan: ChainState;
  find(attributes: object): ChainState;
  match(attributes: object): ChainState;
}

Entity is the primary modeling primitive. Define your attribute schema and indexes in model, provide a configured DynamoDB client and table name, then call query or mutation methods that return chainable clause builders. Call .go() on any chain to execute against DynamoDB.

Service

class Service {
  constructor(entities: Record<string, Entity>, config?: { client?: DynamoDBDocumentClient; table?: string });
  collections: Record<string, (composite: object) => ChainState>;
}

Service groups multiple Entity instances that share a table, enabling cross-entity collection queries. Use it when you need to retrieve items of different types (e.g., Order and OrderItem) in a single paginated DynamoDB query via shared sort-key prefixes.

ExpressionState

class ExpressionState {
  constructor(options?: { prefix?: string });
  names: Record<string, string>;
  values: Record<string, unknown>;
  expression: string;
  incrementName(name: string): string;
}

ExpressionState accumulates ExpressionAttributeNames, ExpressionAttributeValues, and the expression string while building filter or update expressions. It is used internally by FilterFactory and UpdateExpression but can be composed directly when extending the library with custom expression logic.

Working examples

Scenario - Define and query a single entity

A straightforward entity with a composite primary key, queried by partition key with a sort-key begins_with condition.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { Entity } from "./lib/electrodb/entity";

const client = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }));

const Order = new Entity(
  {
    model: { entity: "order", version: "1", service: "store" },
    attributes: {
      storeId:   { type: "string" },
      orderId:   { type: "string" },
      status:    { type: "string", default: "pending" },
      total:     { type: "number" },
      createdAt: { type: "string", default: () => new Date().toISOString() },
    },
    indexes: {
      byStore: {
        pk: { field: "pk", composite: ["storeId"] },
        sk: { field: "sk", composite: ["orderId"] },
      },
    },
  },
  { client, table: "acme-table" }
);

// Query all orders for a store
const { data } = await Order.query.byStore({ storeId: "store-1" }).go();
console.log(data);

// Query with sort key prefix
const { data: recent } = await Order.query
  .byStore({ storeId: "store-1" })
  .begins({ orderId: "2024" })
  .go();
console.log(recent);

Scenario - Put, update, and delete an item

Demonstrates the full mutation lifecycle for a single entity record.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { Entity } from "./lib/electrodb/entity";

const client = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }));

const Product = new Entity(
  {
    model: { entity: "product", version: "1", service: "catalog" },
    attributes: {
      productId: { type: "string" },
      name:      { type: "string", required: true },
      price:     { type: "number" },
      inStock:   { type: "boolean", default: true },
    },
    indexes: {
      primary: {
        pk: { field: "pk", composite: ["productId"] },
        sk: { field: "sk", composite: [] },
      },
    },
  },
  { client, table: "acme-table" }
);

// Create
await Product.put({ productId: "p-001", name: "Widget", price: 9.99 }).go();

// Read
const { data: item } = await Product.get({ productId: "p-001" }).go();

// Update price
await Product.update({ productId: "p-001" }).set({ price: 7.99 }).go();

// Conditional delete
await Product.delete({ productId: "p-001" })
  .where(({ inStock }, op) => op.eq(inStock, true))
  .go();

Scenario - Cross-entity collection query with Service

Two entities sharing a table are grouped in a Service and queried together via a named collection.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { Entity } from "./lib/electrodb/entity";
import { Service } from "./lib/electrodb/service";

const client = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }));
const config = { client, table: "acme-table" };

const Customer = new Entity({
  model: { entity: "customer", version: "1", service: "crm" },
  attributes: {
    customerId: { type: "string" },
    name:       { type: "string" },
  },
  indexes: {
    primary: {
      collection: "customerProfile",
      pk: { field: "pk", composite: ["customerId"] },
      sk: { field: "sk", composite: [] },
    },
  },
}, config);

const Address = new Entity({
  model: { entity: "address", version: "1", service: "crm" },
  attributes: {
    customerId: { type: "string" },
    addressId:  { type: "string" },
    street:     { type: "string" },
  },
  indexes: {
    primary: {
      collection: "customerProfile",
      pk: { field: "pk", composite: ["customerId"] },
      sk: { field: "sk", composite: ["addressId"] },
    },
  },
}, config);

const CrmService = new Service({ Customer, Address });

// Returns both customer and address items in one DynamoDB query
const { data } = await CrmService.collections
  .customerProfile({ customerId: "c-999" })
  .go();

console.log(data.customer);  // Customer items
console.log(data.address);   // Address items

File walkthrough

• clauses.js - Builds the chainable clause API (.where(), .begins(), .between(), .go(), .params()); the surface developers call directly after .query or .update.
• client.js - Normalizes both SDK v2 and v3 DocumentClient configs; use normalizeConfig when wiring custom clients.
• conversions.js - Handles marshaling/unmarshaling of DynamoDB attribute types including sets, maps, and lists.
• entity.js - Defines the Entity class; orchestrates schema parsing, key building, clause chaining, and event emission.
• errors.js - Exports structured error classes; catch ElectroError subclasses to distinguish schema vs. DynamoDB errors.
• events.js - EventManager registers and fires lifecycle events (query, results, error) for logging and instrumentation.
• filterOperations.js - Raw DynamoDB filter operator implementations (eq, gt, lt, contains, begins_with, between, exists).
• filters.js - FilterFactory wraps filterOperations into the .where() fluent API surface.
• operations.js - ExpressionState accumulates names/values maps; formatExpressionName deduplicates reserved-word attribute names.
• schema.js - Schema and AttributeTraverser parse the model definition, validate attribute types, and build composite key metadata.
• service.js - Service class joins multiple entities, infers collection indexes, and routes collection queries.
• set.js - DynamoDBSet wraps native SDK Set types for DynamoDB SS, NS, BS attributes.
• transaction.js - Provides helpers for building and committing transactWrite/transactGet parameter objects.
• types.js - Central enum/constant registry (KeyTypes, MethodTypes, ItemOperations, etc.) consumed by every other module.
• update.js - UpdateExpression builder composes SET, REMOVE, ADD, DELETE clauses into a valid DynamoDB UpdateExpression string.
• updateOperations.js - Individual update operator implementations (set, remove, add, delete, append, ifNotExists).
• util.js - Miscellaneous helpers: instance type detection, model version inference, key padding, and object manipulation.
• validations.js - Standalone validation functions (isString, isBetaServiceConfig, isNameEntityRecordType, etc.) used during schema and input validation.
• where.js - WhereFactory and FilterExpression; builds ConditionExpression and FilterExpression strings for queries and mutations.

Common pitfalls and fixes

• SDK v2 vs v3 DocumentClient mismatch - ElectroDB 3.x expects an AWS SDK v3 DynamoDBDocumentClient; passing a v2 client will silently produce wrong results. Fix: always use @aws-sdk/lib-dynamodb.
• Missing table in config - Omitting table from the config object causes runtime errors only at query time, not at construction. Fix: always pass { client, table: "your-table-name" } to every Entity.
• CJS/ESM interop - The source uses require(); if your project uses ESM ("type": "module"), imports will fail. Fix: use createRequire or set "module": "commonjs" in tsconfig.
• Reserved DynamoDB attribute names - Attributes named name, status, count, etc. collide with DynamoDB reserved words. ElectroDB handles this automatically via formatExpressionName, but only when accessed through its API; raw params bypass this.
• Pagination cursor opacity - ElectroDB encodes LastEvaluatedKey as a base64 URL-safe cursor. Do not parse or construct it manually; always pass it back via .go({ cursor: prev }).
• Collection index mismatch across entities - If two entities in a Service declare the same collection name but different pk/sk field names, queries will silently return empty results. Fix: ensure all entities sharing a collection use identical field values for pk and sk.

Vibe-coding prompt template

I have the ElectroDB library source in `src/lib/electrodb/` and a usage guide in `USAGE.md`.
The upstream package is `user@example.com`.

Please help me integrate ElectroDB into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` and the files under `src/lib/electrodb/` to understand the real exports and APIs.
2. Create an Entity definition for my [describe your data model] with attributes [list attributes] and indexes [describe access patterns].
3. Wire up the DynamoDBDocumentClient from `@aws-sdk/lib-dynamodb` using my existing AWS config.
4. Import `Entity` from `src/lib/electrodb/entity.js` and `Service` from `src/lib/electrodb/service.js`.
5. Write typed query functions for my access patterns using the `.query.<indexName>()` chain and `.go()`.
6. Add a mutation flow: put, update (with `.set()`), and conditional delete (with `.where()`).
7. If I have multiple entities sharing a table, group them in a `Service` and expose collection queries.
8. Show how to handle pagination using the cursor returned by `.go()`.
9. Do not invent any methods or exports not present in `USAGE.md` or the source files.

License and credit

ElectroDB is released under the MIT license. See source/LICENSE if present, or refer to the npm package page and the upstream repository for the authoritative license text. Credit: Tyler Walch (@tywalch).

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.