betterddb 0.2.0 → 0.4.0

package/src/builders/delete-builder.ts

@@ -0,0 +1,84 @@
+import { DynamoDB } from 'aws-sdk';
+import { BetterDDB } from '../betterddb';
+
+export class DeleteBuilder<T> {
+  private condition?: { expression: string; attributeValues: Record<string, any> };
+  private extraTransactItems: DynamoDB.DocumentClient.TransactWriteItemList = [];
+  constructor(private parent: BetterDDB<T>, private key: Partial<T>) {}
+
+  /**
+   * Specify a condition expression for the delete operation.
+   */
+  public withCondition(expression: string, attributeValues: Record<string, any>): this {
+    if (this.condition) {
+      this.condition.expression += ` AND ${expression}`;
+      Object.assign(this.condition.attributeValues, attributeValues);
+    } else {
+      this.condition = { expression, attributeValues };
+    }
+    return this;
+  }
+
+  public async execute(): Promise<void> {
+    if (this.extraTransactItems.length > 0) {
+      // Build our update transaction item.
+      const myTransactItem = this.toTransactDelete();
+      // Combine with extra transaction items.
+      const allItems = [...this.extraTransactItems, myTransactItem];
+      await this.parent.getClient().transactWrite({
+        TransactItems: allItems
+      }).promise();
+      // After transaction, retrieve the updated item.
+      const result = await this.parent.get(this.key).execute();
+      if (result === null) {
+        throw new Error('Item not found after transaction delete');
+      }
+    } else {
+    const params: DynamoDB.DocumentClient.DeleteItemInput = {
+      TableName: this.parent.getTableName(),
+      Key: this.parent.buildKey(this.key)
+    };
+    if (this.condition) {
+      params.ConditionExpression = this.condition.expression;
+        params.ExpressionAttributeValues = this.condition.attributeValues;
+      }
+      await this.parent.getClient().delete(params).promise();
+    }
+  }
+
+  public transactWrite(ops: DynamoDB.DocumentClient.TransactWriteItemList | DynamoDB.DocumentClient.TransactWriteItem): this {
+    if (Array.isArray(ops)) {
+      this.extraTransactItems.push(...ops);
+    } else {
+      this.extraTransactItems.push(ops);
+    }
+    return this;
+  }
+
+  public toTransactDelete(): DynamoDB.DocumentClient.TransactWriteItem {
+    const deleteItem: DynamoDB.DocumentClient.Delete = {
+      TableName: this.parent.getTableName(),
+      Key: this.parent.buildKey(this.key)
+    };
+    if (this.condition) {
+      deleteItem.ConditionExpression = this.condition.expression;
+      deleteItem.ExpressionAttributeValues = this.condition.attributeValues;
+    }
+    return { Delete: deleteItem };
+  }
+
+  public then<TResult1 = void, TResult2 = never>(
+    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2> {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  public catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
+  ): Promise<void | TResult> {
+    return this.execute().catch(onrejected);
+  }
+  public finally(onfinally?: (() => void) | null): Promise<void> {
+    return this.execute().finally(onfinally);
+  }
+}

package/src/builders/get-builder.ts

@@ -0,0 +1,83 @@
+import { DynamoDB } from 'aws-sdk';
+import { BetterDDB } from '../betterddb';
+
+export class GetBuilder<T> {
+  private projectionExpression?: string;
+  private expressionAttributeNames: Record<string, string> = {};
+  private extraTransactItems: DynamoDB.DocumentClient.TransactGetItemList = [];
+  constructor(private parent: BetterDDB<T>, private key: Partial<T>) {}
+
+  /**
+   * Specify a projection by providing an array of attribute names.
+   */
+  public withProjection(attributes: (keyof T)[]): this {
+    this.projectionExpression = attributes.map(attr => `#${String(attr)}`).join(', ');
+    for (const attr of attributes) {
+      this.expressionAttributeNames[`#${String(attr)}`] = String(attr);
+    }
+    return this;
+  }
+
+  public async execute(): Promise<T | null> {
+    if (this.extraTransactItems.length > 0) {
+      // Build our update transaction item.
+      const myTransactItem = this.toTransactGet();
+      // Combine with extra transaction items.
+      const allItems = [...this.extraTransactItems, myTransactItem];
+      await this.parent.getClient().transactGet({
+        TransactItems: allItems
+      }).promise();
+      // After transaction, retrieve the updated item.
+      const result = await this.parent.get(this.key).execute();
+      return result;
+    } else {
+    const params: DynamoDB.DocumentClient.GetItemInput = {
+      TableName: this.parent.getTableName(),
+      Key: this.parent.buildKey(this.key)
+    };
+    if (this.projectionExpression) {
+      params.ProjectionExpression = this.projectionExpression;
+      params.ExpressionAttributeNames = this.expressionAttributeNames;
+    }
+    const result = await this.parent.getClient().get(params).promise();
+    if (!result.Item) return null;
+      return this.parent.getSchema().parse(result.Item);
+    }
+  }
+
+  public transactGet(ops: DynamoDB.DocumentClient.TransactGetItemList | DynamoDB.DocumentClient.TransactGetItem): this {
+    if (Array.isArray(ops)) {
+      this.extraTransactItems.push(...ops);
+    } else {
+      this.extraTransactItems.push(ops);
+    }
+    return this;
+  }
+
+  public toTransactGet(): DynamoDB.DocumentClient.TransactGetItem {
+    const getItem: DynamoDB.DocumentClient.Get = {
+      TableName: this.parent.getTableName(),
+      Key: this.parent.buildKey(this.key)
+    };
+    if (this.projectionExpression) {
+      getItem.ProjectionExpression = this.projectionExpression;
+      getItem.ExpressionAttributeNames = this.expressionAttributeNames;
+    }
+    return { Get: getItem };
+  }
+
+  public then<TResult1 = T | null, TResult2 = never>(
+    onfulfilled?: ((value: T | null) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2> {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  public catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
+  ): Promise<T | null | TResult> {
+    return this.execute().catch(onrejected);
+  }
+  public finally(onfinally?: (() => void) | null): Promise<T | null> {
+    return this.execute().finally(onfinally);
+  }
+}

package/src/builders/query-builder.ts

@@ -0,0 +1,127 @@
+import { DynamoDB } from 'aws-sdk';
+import { BetterDDB } from '../betterddb';
+
+export class QueryBuilder<T> {
+  private filters: string[] = [];
+  private expressionAttributeNames: Record<string, string> = {};
+  private expressionAttributeValues: Record<string, any> = {};
+  private indexName?: string;
+  private sortKeyCondition?: string; // You can extend this to support a fluent sort builder.
+  private limit?: number;
+  private lastKey?: Record<string, any>;
+  private ascending: boolean = true;
+
+  constructor(private parent: BetterDDB<T>, private key: Partial<T>) {}
+
+  public usingIndex(indexName: string): this {
+    this.indexName = indexName;
+    return this;
+  }
+
+  public sortAscending(): this {
+    this.ascending = true;
+    return this;
+  }
+
+  public sortDescending(): this {
+    this.ascending = false;
+    return this;
+  }
+
+  public where(
+    attribute: keyof T,
+    operator: 'eq' | 'begins_with' | 'between',
+    values: any | [any, any]
+  ): this {
+    const attrStr = String(attribute);
+    const nameKey = `#attr_${attrStr}`;
+    this.expressionAttributeNames[nameKey] = attrStr;
+
+    if (operator === 'eq') {
+      const valueKey = `:val_${attrStr}`;
+      this.expressionAttributeValues[valueKey] = values;
+      this.filters.push(`${nameKey} = ${valueKey}`);
+    } else if (operator === 'begins_with') {
+      const valueKey = `:val_${attrStr}`;
+      this.expressionAttributeValues[valueKey] = values;
+      this.filters.push(`begins_with(${nameKey}, ${valueKey})`);
+    } else if (operator === 'between') {
+      if (!Array.isArray(values) || values.length !== 2) {
+        throw new Error(`For 'between' operator, values must be a tuple of two items`);
+      }
+      const valueKeyStart = `:val_start_${attrStr}`;
+      const valueKeyEnd = `:val_end_${attrStr}`;
+      this.expressionAttributeValues[valueKeyStart] = values[0];
+      this.expressionAttributeValues[valueKeyEnd] = values[1];
+      this.filters.push(`${nameKey} BETWEEN ${valueKeyStart} AND ${valueKeyEnd}`);
+    } else {
+      throw new Error(`Unsupported operator: ${operator}`);
+    }
+    return this;
+  }
+
+  public limitResults(limit: number): this {
+    this.limit = limit;
+    return this;
+  }
+
+  public startFrom(lastKey: Record<string, any>): this {
+    this.lastKey = lastKey;
+    return this;
+  }
+
+  /**
+   * Executes the query and returns a Promise that resolves with an array of items.
+   */
+  public async execute(): Promise<T[]> {
+    // Build a simple key condition for the partition key.
+    const keys = this.parent.getKeys();
+    const pkName = keys.primary.name;
+    this.expressionAttributeNames['#pk'] = pkName;
+
+    // Cast the built key to a record so that we can index by string.
+    const builtKey = this.parent.buildKey(this.key) as Record<string, any>;
+    this.expressionAttributeValues[':pk_value'] = builtKey[pkName];
+
+    let keyConditionExpression = `#pk = :pk_value`;
+    // If a sortKeyCondition was set via another fluent method, append it.
+    if (this.sortKeyCondition) {
+      keyConditionExpression += ` AND ${this.sortKeyCondition}`;
+    }
+
+    // If any filters were added, set them as FilterExpression.
+    const params: DynamoDB.DocumentClient.QueryInput = {
+      TableName: this.parent.getTableName(),
+      KeyConditionExpression: keyConditionExpression,
+      ExpressionAttributeNames: this.expressionAttributeNames,
+      ExpressionAttributeValues: this.expressionAttributeValues,
+      ScanIndexForward: this.ascending,
+      Limit: this.limit,
+      ExclusiveStartKey: this.lastKey,
+      IndexName: this.indexName
+    };
+
+    if (this.filters.length > 0) {
+      params.FilterExpression = this.filters.join(' AND ');
+    }
+
+    const result = await this.parent.getClient().query(params).promise();
+    return this.parent.getSchema().array().parse(result.Items);
+  }
+
+  // Thenable implementation.
+  public then<TResult1 = T[], TResult2 = never>(
+    onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2> {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  public catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
+  ): Promise<T[] | TResult> {
+    return this.execute().catch(onrejected);
+  }
+  public finally(onfinally?: (() => void) | null): Promise<T[]> {
+    return this.execute().finally(onfinally);
+  }
+}

package/src/builders/scan-builder.ts

@@ -0,0 +1,90 @@
+import { DynamoDB } from 'aws-sdk';
+import { BetterDDB } from '../betterddb';
+
+export class ScanBuilder<T> {
+  private filters: string[] = [];
+  private expressionAttributeNames: Record<string, string> = {};
+  private expressionAttributeValues: Record<string, any> = {};
+  private limit?: number;
+  private lastKey?: Record<string, any>;
+
+  constructor(private parent: BetterDDB<T>) {}
+
+  public where(
+    attribute: keyof T,
+    operator: 'eq' | 'begins_with' | 'between',
+    values: any | [any, any]
+  ): this {
+    const attrStr = String(attribute);
+    const nameKey = `#attr_${attrStr}`;
+    this.expressionAttributeNames[nameKey] = attrStr;
+
+    if (operator === 'eq') {
+      const valueKey = `:val_${attrStr}`;
+      this.expressionAttributeValues[valueKey] = values;
+      this.filters.push(`${nameKey} = ${valueKey}`);
+    } else if (operator === 'begins_with') {
+      const valueKey = `:val_${attrStr}`;
+      this.expressionAttributeValues[valueKey] = values;
+      this.filters.push(`begins_with(${nameKey}, ${valueKey})`);
+    } else if (operator === 'between') {
+      if (!Array.isArray(values) || values.length !== 2) {
+        throw new Error(`For 'between' operator, values must be a tuple of two items`);
+      }
+      const valueKeyStart = `:val_start_${attrStr}`;
+      const valueKeyEnd = `:val_end_${attrStr}`;
+      this.expressionAttributeValues[valueKeyStart] = values[0];
+      this.expressionAttributeValues[valueKeyEnd] = values[1];
+      this.filters.push(`${nameKey} BETWEEN ${valueKeyStart} AND ${valueKeyEnd}`);
+    } else {
+      throw new Error(`Unsupported operator: ${operator}`);
+    }
+    return this;
+  }
+
+  public limitResults(limit: number): this {
+    this.limit = limit;
+    return this;
+  }
+
+  public startFrom(lastKey: Record<string, any>): this {
+    this.lastKey = lastKey;
+    return this;
+  }
+
+  /**
+   * Executes the scan and returns a Promise that resolves with an array of items.
+   */
+  public async execute(): Promise<T[]> {
+    const params: DynamoDB.DocumentClient.ScanInput = {
+      TableName: this.parent.getTableName(),
+      ExpressionAttributeNames: this.expressionAttributeNames,
+      ExpressionAttributeValues: this.expressionAttributeValues,
+      Limit: this.limit,
+      ExclusiveStartKey: this.lastKey
+    };
+
+    if (this.filters.length > 0) {
+      params.FilterExpression = this.filters.join(' AND ');
+    }
+
+    const result = await this.parent.getClient().scan(params).promise();
+    return this.parent.getSchema().array().parse(result.Items);
+  }
+
+  // Thenable implementation.
+  public then<TResult1 = T[], TResult2 = never>(
+    onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2> {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  public catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
+  ): Promise<T[] | TResult> {
+    return this.execute().catch(onrejected);
+  }
+  public finally(onfinally?: (() => void) | null): Promise<T[]> {
+    return this.execute().finally(onfinally);
+  }
+}

package/src/builders/update-builder.ts

@@ -0,0 +1,230 @@
+
+import { DynamoDB } from 'aws-sdk';
+import { BetterDDB } from '../betterddb';
+
+interface UpdateActions<T> {
+  set?: Partial<T>;
+  remove?: (keyof T)[];
+  add?: Partial<Record<keyof T, number | Set<any>>>;
+  delete?: Partial<Record<keyof T, Set<any>>>;
+}
+
+export class UpdateBuilder<T> {
+  private actions: UpdateActions<T> = {};
+  private condition?: { expression: string; attributeValues: Record<string, any> };
+  private expectedVersion?: number;
+  // When using transaction mode, we store extra transaction items.
+  private extraTransactItems: DynamoDB.DocumentClient.TransactWriteItemList = [];
+
+  // Reference to the parent BetterDDB instance and key.
+  constructor(private parent: BetterDDB<T>, private key: Partial<T>, expectedVersion?: number) {
+    this.expectedVersion = expectedVersion;
+  }
+
+  // Chainable methods:
+  public set(attrs: Partial<T>): this {
+    this.actions.set = { ...this.actions.set, ...attrs };
+    return this;
+  }
+
+  public remove(attrs: (keyof T)[]): this {
+    this.actions.remove = [...(this.actions.remove || []), ...attrs];
+    return this;
+  }
+
+  public add(attrs: Partial<Record<keyof T, number | Set<any>>>): this {
+    this.actions.add = { ...this.actions.add, ...attrs };
+    return this;
+  }
+
+  public delete(attrs: Partial<Record<keyof T, Set<any>>>): this {
+    this.actions.delete = { ...this.actions.delete, ...attrs };
+    return this;
+  }
+
+  /**
+   * Adds a condition expression to the update.
+   */
+  public setCondition(expression: string, attributeValues: Record<string, any>): this {
+    if (this.condition) {
+      // Merge conditions with AND.
+      this.condition.expression += ` AND ${expression}`;
+      Object.assign(this.condition.attributeValues, attributeValues);
+    } else {
+      this.condition = { expression, attributeValues };
+    }
+    return this;
+  }
+
+  /**
+   * Specifies additional transaction items to include when executing this update as a transaction.
+   */
+  public transactWrite(ops: DynamoDB.DocumentClient.TransactWriteItemList | DynamoDB.DocumentClient.TransactWriteItem): this {
+    if (Array.isArray(ops)) {
+      this.extraTransactItems.push(...ops);
+    } else {
+      this.extraTransactItems.push(ops);
+    }
+    return this;
+  }
+
+  /**
+   * Builds the update expression and associated maps.
+   */
+  private buildExpression(): {
+    updateExpression: string;
+    attributeNames: Record<string, string>;
+    attributeValues: Record<string, any>;
+  } {
+    const ExpressionAttributeNames: Record<string, string> = {};
+    const ExpressionAttributeValues: Record<string, any> = {};
+    const clauses: string[] = [];
+
+    // Build SET clause.
+    if (this.actions.set) {
+      const setParts: string[] = [];
+      for (const [attr, value] of Object.entries(this.actions.set)) {
+        const nameKey = `#set_${attr}`;
+        const valueKey = `:set_${attr}`;
+        ExpressionAttributeNames[nameKey] = attr;
+        ExpressionAttributeValues[valueKey] = value;
+        setParts.push(`${nameKey} = ${valueKey}`);
+      }
+      if (setParts.length > 0) {
+        clauses.push(`SET ${setParts.join(', ')}`);
+      }
+    }
+
+    // Build REMOVE clause.
+    if (this.actions.remove && this.actions.remove.length > 0) {
+      const removeParts = this.actions.remove.map(attr => {
+        const nameKey = `#remove_${String(attr)}`;
+        ExpressionAttributeNames[nameKey] = String(attr);
+        return nameKey;
+      });
+      clauses.push(`REMOVE ${removeParts.join(', ')}`);
+    }
+
+    // Build ADD clause.
+    if (this.actions.add) {
+      const addParts: string[] = [];
+      for (const [attr, value] of Object.entries(this.actions.add)) {
+        const nameKey = `#add_${attr}`;
+        const valueKey = `:add_${attr}`;
+        ExpressionAttributeNames[nameKey] = attr;
+        ExpressionAttributeValues[valueKey] = value;
+        addParts.push(`${nameKey} ${valueKey}`);
+      }
+      if (addParts.length > 0) {
+        clauses.push(`ADD ${addParts.join(', ')}`);
+      }
+    }
+
+    // Build DELETE clause.
+    if (this.actions.delete) {
+      const deleteParts: string[] = [];
+      for (const [attr, value] of Object.entries(this.actions.delete)) {
+        const nameKey = `#delete_${attr}`;
+        const valueKey = `:delete_${attr}`;
+        ExpressionAttributeNames[nameKey] = attr;
+        ExpressionAttributeValues[valueKey] = value;
+        deleteParts.push(`${nameKey} ${valueKey}`);
+      }
+      if (deleteParts.length > 0) {
+        clauses.push(`DELETE ${deleteParts.join(', ')}`);
+      }
+    }
+
+    // Incorporate expectedVersion if provided.
+    if (this.expectedVersion !== undefined) {
+      ExpressionAttributeNames['#version'] = 'version';
+      ExpressionAttributeValues[':expectedVersion'] = this.expectedVersion;
+      ExpressionAttributeValues[':newVersion'] = this.expectedVersion + 1;
+
+      // Append version update in SET clause.
+      const versionClause = '#version = :newVersion';
+      const setIndex = clauses.findIndex(clause => clause.startsWith('SET '));
+      if (setIndex >= 0) {
+        clauses[setIndex] += `, ${versionClause}`;
+      } else {
+        clauses.push(`SET ${versionClause}`);
+      }
+
+      // Ensure condition expression includes version check.
+      if (this.condition && this.condition.expression) {
+        this.condition.expression += ` AND #version = :expectedVersion`;
+      } else {
+        this.condition = { expression: '#version = :expectedVersion', attributeValues: {} };
+      }
+    }
+
+    // Merge any provided condition attribute values.
+    if (this.condition) {
+      Object.assign(ExpressionAttributeValues, this.condition.attributeValues);
+    }
+
+    return {
+      updateExpression: clauses.join(' '),
+      attributeNames: ExpressionAttributeNames,
+      attributeValues: ExpressionAttributeValues
+    };
+  }
+
+  /**
+   * Returns a transaction update item that can be included in a transactWrite call.
+   */
+  public toTransactUpdate(): DynamoDB.DocumentClient.TransactWriteItem {
+    const { updateExpression, attributeNames, attributeValues } = this.buildExpression();
+    const updateItem: DynamoDB.DocumentClient.Update = {
+      TableName: this.parent.getTableName(),
+      Key: this.parent.buildKey(this.key),
+      UpdateExpression: updateExpression,
+      ExpressionAttributeNames: attributeNames,
+      ExpressionAttributeValues: attributeValues
+    };
+    if (this.condition && this.condition.expression) {
+      updateItem.ConditionExpression = this.condition.expression;
+    }
+    return { Update: updateItem };
+  }
+
+  /**
+   * Commits the update immediately by calling the parent's update method.
+   */
+  public async execute(): Promise<T> {
+    if (this.extraTransactItems.length > 0) {
+      // Build our update transaction item.
+      const myTransactItem = this.toTransactUpdate();
+      // Combine with extra transaction items.
+      const allItems = [...this.extraTransactItems, myTransactItem];
+      await this.parent.getClient().transactWrite({
+        TransactItems: allItems
+      }).promise();
+      // After transaction, retrieve the updated item.
+      const result = await this.parent.get(this.key).execute();
+      if (result === null) {
+        throw new Error('Item not found after transaction update');
+      }
+      return result;
+    } else {
+      // Normal update flow.
+      const { updateExpression, attributeNames, attributeValues } = this.buildExpression();
+      const params: DynamoDB.DocumentClient.UpdateItemInput = {
+        TableName: this.parent.getTableName(),
+        Key: this.parent.buildKey(this.key),
+        UpdateExpression: updateExpression,
+        ExpressionAttributeNames: attributeNames,
+        ExpressionAttributeValues: attributeValues,
+        ReturnValues: 'ALL_NEW'
+      };
+      if (this.condition && this.condition.expression) {
+        params.ConditionExpression = this.condition.expression;
+      }
+      const result = await this.parent.getClient().update(params).promise();
+      if (!result.Attributes) {
+        throw new Error('No attributes returned after update');
+      }
+      return this.parent.getSchema().parse(result.Attributes);
+    }
+  }
+}

package/test/create.test.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { BetterDDB } from '../src/betterddb';
+import { DynamoDB } from 'aws-sdk';
+import { createTestTable, deleteTestTable } from './utils/table-setup';
+
+const TEST_TABLE = "create-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_NAME = 'USER';
+const PRIMARY_KEY = 'id';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'email';
+const SORT_KEY_TYPE = 'S';
+const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }];
+const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }];
+const client = new DynamoDB.DocumentClient({
+  region: REGION,
+  endpoint: ENDPOINT,
+});
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}).passthrough();
+
+const userDdb = new BetterDDB({
+  schema: UserSchema,
+  tableName: TEST_TABLE,
+  entityName: ENTITY_NAME,
+  keys: {
+    primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
+    sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
+  },
+  client,
+  autoTimestamps: true,
+});
+
+beforeAll(async () => {
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+});
+
+afterAll(async () => {
+  await deleteTestTable(TEST_TABLE);
+});
+
+describe('BetterDDB - Create Operation', () => {
+  it('should insert an item using CreateBuilder', async () => {
+    const user = { id: 'user-123', name: 'John Doe', email: 'john@example.com' };
+    await userDdb.create(user as any).execute();
+    const createdUser = await userDdb.get({ id: 'user-123', email: 'john@example.com' }).execute();
+    expect(createdUser).not.toBeNull();
+    expect(createdUser?.id).toBe('user-123');
+    expect(createdUser).toHaveProperty('createdAt');
+    expect(createdUser).toHaveProperty('updatedAt');
+  });
+});