Skip to content

Getting Started

Jump to bottom
Miguel Guevara edited this page Jan 9, 2026 · 1 revision

Getting Started with Dynamite

Welcome to Dynamite! This guide will walk you through creating your first application with this modern, decorator-first ORM for DynamoDB.

Prerequisites

  • Node.js 16+ installed
  • Basic TypeScript knowledge
  • AWS account or DynamoDB Local
  • Completed Installation guide

Your First Model

Let's create a simple User model. In Dynamite, models are classes that extend Table and use decorators to define their structure.

import { Table, PrimaryKey, Default, CreationOptional } from "@arcaelas/dynamite";

class User extends Table<User> {
  // Primary key with auto-generated UUID
  @PrimaryKey()
  @Default(() => crypto.randomUUID())
  declare id: CreationOptional<string>;

  // Required field during creation
  declare name: string;

  // Optional field with default value
  @Default(() => "customer")
  declare role: CreationOptional<string>;
}

Key concepts:

  • @PrimaryKey() marks the primary key (partition key in DynamoDB)
  • @Default() provides automatic default values
  • CreationOptional<T> makes fields optional during creation but required in instances
  • declare is TypeScript syntax for class properties

Configuration

Configure your DynamoDB connection:

import { Dynamite } from "@arcaelas/dynamite";

// For local development
const dynamite = new Dynamite({
  region: "us-east-1",
  endpoint: "http://localhost:8000",
  tables: [User],
  credentials: {
    accessKeyId: "test",
    secretAccessKey: "test"
  }
});
await dynamite.connect();

Creating Records

There are multiple ways to create records:

Using create() method

// Create with required fields only
const user1 = await User.create({
  name: "John Doe"
  // id and role are optional (auto-generated/defaulted)
});

console.log(user1.id);   // "550e8400-e29b-41d4-a716-446655440000"
console.log(user1.name); // "John Doe"
console.log(user1.role); // "customer"

// Create with all fields
const user2 = await User.create({
  id: "custom-id",
  name: "Jane Smith",
  role: "admin"
});

Creating multiple records

const users = await Promise.all([
  User.create({ name: "Alice" }),
  User.create({ name: "Bob" }),
  User.create({ name: "Charlie" })
]);

console.log(`Created ${users.length} users`);

Reading Records

Dynamite provides several methods to query your data:

Get all records

const all_users = await User.where({});
console.log(`Total users: ${all_users.length}`);

Filter by fields

// Filter by exact match
const admins = await User.where({ role: "admin" });

// Filter by multiple conditions
const admin_johns = await User.where({
  name: "John Doe",
  role: "admin"
});

Get first or last record

// Get first user
const first_user = await User.first({});

// Get first admin
const first_admin = await User.first({ role: "admin" });

// Get last user
const last_user = await User.last({});

Advanced queries with operators

// Greater than or equal
const premium_users = await User.where("id", ">=", "user-100");

// String contains
const gmail_users = await User.where("email", "$include", "gmail");

// In array
const special_roles = await User.where("role", "in", ["admin", "premium", "vip"]);

// Not equal
const non_customers = await User.where("role", "!=", "customer");

Query with options

// Limit results
const first_10_users = await User.where({}, { limit: 10 });

// Pagination (skip and limit)
const page_2_users = await User.where({}, {
  limit: 10,
  skip: 10
});

// Sort order
const sorted_users = await User.where({}, { order: "DESC" });

// Select specific attributes
const user_names = await User.where({}, {
  attributes: ["id", "name"]
});

Updating Records

You can update records using instance methods or static methods:

Using instance save() method

// Get a user
const user = await User.first({ name: "John Doe" });

if (user) {
  // Modify properties
  user.name = "John Smith";
  user.role = "premium";

  // Save changes
  await user.save();

  console.log("User updated successfully");
}

Using instance update() method

const user = await User.first({ name: "John Doe" });

if (user) {
  // Update multiple fields at once
  await user.update({
    name: "John Smith",
    role: "premium"
  });
}

Using static update() method

// Update by filter - returns number of updated records
await User.update(
  { name: "John Smith", role: "premium" },  // updates
  { id: "user-123" }                        // filters
);

Deleting Records

Delete records using instance or static methods:

Using instance destroy() method

const user = await User.first({ name: "John Doe" });

if (user) {
  await user.destroy();
  console.log("User deleted");
}

Using static delete() method

// Delete by filters
await User.delete({ id: "user-123" });

// Delete multiple by condition
await User.delete({ active: false });

Adding Timestamps

Timestamps track when records are created and updated. Use @CreatedAt and @UpdatedAt decorators:

import {
  Table,
  PrimaryKey,
  Default,
  CreatedAt,
  UpdatedAt,
  CreationOptional
} from "@arcaelas/dynamite";

class User extends Table<User> {
  @PrimaryKey()
  @Default(() => crypto.randomUUID())
  declare id: CreationOptional<string>;

  declare name: string;

  // Auto-set on creation
  @CreatedAt()
  declare created_at: CreationOptional<string>;

  // Auto-update on save
  @UpdatedAt()
  declare updated_at: CreationOptional<string>;
}

// Usage
const user = await User.create({ name: "John Doe" });

console.log(user.created_at); // "2024-01-15T10:30:00.000Z"
console.log(user.updated_at); // "2024-01-15T10:30:00.000Z"

// Update user
user.name = "John Smith";
await user.save();

console.log(user.updated_at); // "2024-01-15T10:35:00.000Z" (updated!)

Quick Reference

Essential Decorators

Decorator Purpose Example
@PrimaryKey() Primary key @PrimaryKey() declare id: string
@Default(fn) Default value @Default(() => uuid()) declare id: string
@CreatedAt() Auto timestamp on create @CreatedAt() declare created_at: string
@UpdatedAt() Auto timestamp on update @UpdatedAt() declare updated_at: string
@Validate(fn) Validation @Validate((v) => v.length > 0) declare name: string
@Mutate(fn) Transform data @Mutate((v) => v.trim()) declare email: string
@NotNull() Not null check @NotNull() declare email: string

CRUD Operations

// Create
const user = await User.create({ name: "John" });

// Read
const users = await User.where({ active: true });
const user = await User.first({ id: "123" });

// Update
user.name = "Jane";
await user.save();

// Delete
await user.destroy();

Next Steps

Need help? Check the GitHub Issues

Clone this wiki locally