betterddb 0.4.9 → 0.5.0

package/README.md

@@ -61,8 +61,8 @@ const userDdb = new BetterDDB({
     }
   },
   client,
-  autoTimestamps: true,
-  entityName: 'USER'
+  timestamps: true,
+  entityType: 'USER'
 });
 
 (async () => {

package/lib/betterddb.d.ts

@@ -63,7 +63,7 @@ export interface KeysConfig<T> {
 export interface BetterDDBOptions<T> {
     schema: z.ZodType<T, z.ZodTypeDef, any>;
     tableName: string;
-    entityName: string;
+    entityType: string;
     keys: KeysConfig<T>;
     client: DynamoDBDocumentClient;
     /**
@@ -73,7 +73,7 @@ export interface BetterDDBOptions<T> {
      *
      * (T should include these fields if enabled.)
      */
-    autoTimestamps?: boolean;
+    timestamps?: boolean;
 }
 /**
  * BetterDDB is a definition-based DynamoDB wrapper library.
@@ -81,16 +81,17 @@ export interface BetterDDBOptions<T> {
 export declare class BetterDDB<T> {
     protected schema: z.ZodType<T, z.ZodTypeDef, any>;
     protected tableName: string;
-    protected entityName: string;
+    protected entityType: string;
     protected client: DynamoDBDocumentClient;
     protected keys: KeysConfig<T>;
-    protected autoTimestamps: boolean;
+    protected timestamps: boolean;
     constructor(options: BetterDDBOptions<T>);
     getKeys(): KeysConfig<T>;
     getTableName(): string;
     getClient(): DynamoDBDocumentClient;
     getSchema(): z.ZodType<T, z.ZodTypeDef, any>;
-    getAutoTimestamps(): boolean;
+    getTimestamps(): boolean;
+    getEntityType(): string;
     protected getKeyValue(def: KeyDefinition<T>, rawKey: Partial<T>): string;
     /**
      * Build the primary key from a raw key object.
@@ -118,7 +119,7 @@ export declare class BetterDDB<T> {
     /**
      * Update an item.
      */
-    update(key: Partial<T>, expectedVersion?: number): UpdateBuilder<T>;
+    update(key: Partial<T>): UpdateBuilder<T>;
     /**
      * Delete an item.
      */

package/lib/betterddb.js

@@ -16,10 +16,10 @@ class BetterDDB {
         var _a;
         this.schema = options.schema;
         this.tableName = options.tableName;
-        this.entityName = options.entityName.toUpperCase();
+        this.entityType = options.entityType.toUpperCase();
         this.keys = options.keys;
         this.client = options.client;
-        this.autoTimestamps = (_a = options.autoTimestamps) !== null && _a !== void 0 ? _a : false;
+        this.timestamps = (_a = options.timestamps) !== null && _a !== void 0 ? _a : false;
     }
     getKeys() {
         return this.keys;
@@ -33,8 +33,11 @@ class BetterDDB {
     getSchema() {
         return this.schema;
     }
-    getAutoTimestamps() {
-        return this.autoTimestamps;
+    getTimestamps() {
+        return this.timestamps;
+    }
+    getEntityType() {
+        return this.entityType;
     }
     // Helper: Retrieve the key value from a KeyDefinition.
     getKeyValue(def, rawKey) {
@@ -124,8 +127,8 @@ class BetterDDB {
     /**
      * Update an item.
      */
-    update(key, expectedVersion) {
-        return new update_builder_1.UpdateBuilder(this, key, expectedVersion);
+    update(key) {
+        return new update_builder_1.UpdateBuilder(this, key);
     }
     /**
      * Delete an item.

package/lib/builders/create-builder.js

@@ -9,6 +9,7 @@ class CreateBuilder {
         this.extraTransactItems = [];
     }
     async execute() {
+        const validated = this.parent.getSchema().parse(this.item);
         if (this.extraTransactItems.length > 0) {
             // Build our update transaction item.
             const myTransactItem = this.toTransactPut();
@@ -25,14 +26,11 @@ class CreateBuilder {
             return result;
         }
         else {
-            let item = this.item;
-            if (this.parent.getAutoTimestamps()) {
+            let finalItem = { ...this.item, entityType: this.parent.getEntityType() };
+            if (this.parent.getTimestamps()) {
                 const now = new Date().toISOString();
-                item = { ...item, createdAt: now, updatedAt: now };
+                finalItem = { ...finalItem, createdAt: now, updatedAt: now };
             }
-            // Validate the item using the schema.
-            const validated = this.parent.getSchema().parse(item);
-            let finalItem = { ...validated };
             // Compute and merge primary key.
             const computedKeys = this.parent.buildKey(validated);
             finalItem = { ...finalItem, ...computedKeys };

package/lib/builders/query-builder.d.ts

@@ -1,5 +1,6 @@
 import { BetterDDB } from '../betterddb';
 import { Operator } from '../operator';
+import { PaginatedResult } from '../types/paginated-result';
 export declare class QueryBuilder<T> {
     private parent;
     private key;
@@ -22,5 +23,5 @@ export declare class QueryBuilder<T> {
     /**
      * Executes the query and returns a Promise that resolves with an array of items.
      */
-    execute(): Promise<T[]>;
+    execute(): Promise<PaginatedResult<T>>;
 }

package/lib/builders/query-builder.js

@@ -118,7 +118,7 @@ class QueryBuilder {
      * Executes the query and returns a Promise that resolves with an array of items.
      */
     async execute() {
-        var _a, _b;
+        var _a, _b, _c;
         const keys = this.parent.getKeys();
         let pkName = keys.primary.name;
         let builtKey = this.parent.buildKey(this.key);
@@ -142,12 +142,12 @@ class QueryBuilder {
             ExclusiveStartKey: this.lastKey,
             IndexName: (_b = (_a = this.index) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : undefined,
         };
-        if (this.filterConditions.length > 0) {
-            params.FilterExpression = this.filterConditions.join(' AND ');
-        }
-        console.log(params);
+        this.filterConditions.push(`#entity = :entity_value`);
+        this.expressionAttributeNames['#entity'] = 'entityType';
+        this.expressionAttributeValues[':entity_value'] = this.parent.getEntityType();
+        params.FilterExpression = this.filterConditions.join(' AND ');
         const result = await this.parent.getClient().send(new lib_dynamodb_1.QueryCommand(params));
-        return this.parent.getSchema().array().parse(result.Items);
+        return { items: this.parent.getSchema().array().parse(result.Items), lastKey: (_c = result.LastEvaluatedKey) !== null && _c !== void 0 ? _c : undefined };
     }
 }
 exports.QueryBuilder = QueryBuilder;

package/lib/builders/scan-builder.d.ts

@@ -1,5 +1,6 @@
 import { BetterDDB } from '../betterddb';
 import { Operator } from '../operator';
+import { PaginatedResult } from '../types/paginated-result';
 export declare class ScanBuilder<T> {
     private parent;
     private filters;
@@ -14,5 +15,5 @@ export declare class ScanBuilder<T> {
     /**
      * Executes the scan and returns a Promise that resolves with an array of items.
      */
-    execute(): Promise<T[]>;
+    execute(): Promise<PaginatedResult<T>>;
 }

package/lib/builders/scan-builder.js

@@ -49,6 +49,7 @@ class ScanBuilder {
      * Executes the scan and returns a Promise that resolves with an array of items.
      */
     async execute() {
+        var _a;
         const params = {
             TableName: this.parent.getTableName(),
             ExpressionAttributeNames: this.expressionAttributeNames,
@@ -60,7 +61,7 @@ class ScanBuilder {
             params.FilterExpression = this.filters.join(' AND ');
         }
         const result = await this.parent.getClient().send(new lib_dynamodb_1.ScanCommand(params));
-        return this.parent.getSchema().array().parse(result.Items);
+        return { items: this.parent.getSchema().array().parse(result.Items), lastKey: (_a = result.LastEvaluatedKey) !== null && _a !== void 0 ? _a : undefined };
     }
 }
 exports.ScanBuilder = ScanBuilder;

package/lib/builders/update-builder.d.ts

@@ -5,9 +5,8 @@ export declare class UpdateBuilder<T> {
     private key;
     private actions;
     private condition?;
-    private expectedVersion?;
     private extraTransactItems;
-    constructor(parent: BetterDDB<T>, key: Partial<T>, expectedVersion?: number);
+    constructor(parent: BetterDDB<T>, key: Partial<T>);
     set(attrs: Partial<T>): this;
     remove(attrs: (keyof T)[]): this;
     add(attrs: Partial<Record<keyof T, number | Set<any>>>): this;

package/lib/builders/update-builder.js

@@ -4,13 +4,12 @@ exports.UpdateBuilder = void 0;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 class UpdateBuilder {
     // Reference to the parent BetterDDB instance and key.
-    constructor(parent, key, expectedVersion) {
+    constructor(parent, key) {
         this.parent = parent;
         this.key = key;
         this.actions = {};
         // When using transaction mode, we store extra transaction items.
         this.extraTransactItems = [];
-        this.expectedVersion = expectedVersion;
     }
     // Chainable methods:
     set(attrs) {
@@ -113,28 +112,6 @@ class UpdateBuilder {
                 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);

package/lib/types/paginated-result.d.ts

@@ -0,0 +1,4 @@
+export type PaginatedResult<T> = {
+    items: T[];
+    lastKey: Record<string, any> | undefined;
+};

package/lib/types/paginated-result.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "betterddb",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "description": "A definition-based DynamoDB wrapper library that provides a schema-driven and fully typesafe DAL.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/betterddb.ts

@@ -72,7 +72,7 @@ export interface KeysConfig<T> {
 export interface BetterDDBOptions<T> {
   schema: z.ZodType<T, z.ZodTypeDef, any>;
   tableName: string;
-  entityName: string;
+  entityType: string;
   keys: KeysConfig<T>;
   client: DynamoDBDocumentClient;
   /**
@@ -82,7 +82,7 @@ export interface BetterDDBOptions<T> {
    *
    * (T should include these fields if enabled.)
    */
-  autoTimestamps?: boolean;
+  timestamps?: boolean;
 }
 
 /**
@@ -91,18 +91,18 @@ export interface BetterDDBOptions<T> {
 export class BetterDDB<T> {
   protected schema: z.ZodType<T, z.ZodTypeDef, any>;
   protected tableName: string;
-  protected entityName: string;
+  protected entityType: string;
   protected client: DynamoDBDocumentClient;
   protected keys: KeysConfig<T>;
-  protected autoTimestamps: boolean;
+  protected timestamps: boolean;
 
   constructor(options: BetterDDBOptions<T>) {
     this.schema = options.schema;
     this.tableName = options.tableName;
-    this.entityName = options.entityName.toUpperCase();
+    this.entityType = options.entityType.toUpperCase();
     this.keys = options.keys;
     this.client = options.client;
-    this.autoTimestamps = options.autoTimestamps ?? false;
+    this.timestamps = options.timestamps ?? false;
   }
 
   public getKeys(): KeysConfig<T> {
@@ -122,8 +122,12 @@ export class BetterDDB<T> {
     return this.schema;
   }
 
-  public getAutoTimestamps(): boolean {
-    return this.autoTimestamps;
+  public getTimestamps(): boolean {
+    return this.timestamps;
+  }
+
+  public getEntityType(): string {
+    return this.entityType;
   }
 
   // Helper: Retrieve the key value from a KeyDefinition.
@@ -223,8 +227,8 @@ export class BetterDDB<T> {
   /**
    * Update an item.
    */
-  public update(key: Partial<T>, expectedVersion?: number): UpdateBuilder<T> {
-    return new UpdateBuilder<T>(this, key, expectedVersion);
+  public update(key: Partial<T>): UpdateBuilder<T> {
+    return new UpdateBuilder<T>(this, key);
   }
 
   /**

package/src/builders/create-builder.ts

@@ -9,6 +9,7 @@ export class CreateBuilder<T> {
   constructor(private parent: BetterDDB<T>, private item: T) {}
 
   public async execute(): Promise<T> {
+    const validated = this.parent.getSchema().parse(this.item);
     if (this.extraTransactItems.length > 0) {
       // Build our update transaction item.
       const myTransactItem = this.toTransactPut();
@@ -24,14 +25,12 @@ export class CreateBuilder<T> {
       }
       return result;
     } else {
-    let item = this.item;
-    if (this.parent.getAutoTimestamps()) {
+
+    let finalItem: T = { ...this.item , entityType: this.parent.getEntityType() };
+    if (this.parent.getTimestamps()) {
       const now = new Date().toISOString();
-      item = { ...item, createdAt: now, updatedAt: now } as T;
+      finalItem = { ...finalItem, createdAt: now, updatedAt: now } as T;
     }
-    // Validate the item using the schema.
-    const validated = this.parent.getSchema().parse(item);
-    let finalItem = { ...validated };
 
     // Compute and merge primary key.
     const computedKeys = this.parent.buildKey(validated as Partial<T>);

package/src/builders/query-builder.ts

@@ -1,6 +1,8 @@
 import { QueryCommand, QueryCommandInput } from '@aws-sdk/lib-dynamodb';
 import { BetterDDB, GSIConfig } from '../betterddb';
 import { getOperatorExpression, Operator } from '../operator';
+import { PaginatedResult } from '../types/paginated-result';
+
 export class QueryBuilder<T> {
   private keyConditions: string[] = [];
   private filterConditions: string[] = [];
@@ -133,7 +135,7 @@ export class QueryBuilder<T> {
   /**
    * Executes the query and returns a Promise that resolves with an array of items.
    */
-  public async execute(): Promise<T[]> {
+  public async execute(): Promise<PaginatedResult<T>> {
     const keys = this.parent.getKeys();
     let pkName = keys.primary.name;
     let builtKey = this.parent.buildKey(this.key) as Record<string, any>;
@@ -160,11 +162,12 @@ export class QueryBuilder<T> {
       IndexName: this.index?.name ?? undefined,
     };
 
-    if (this.filterConditions.length > 0) {
-      params.FilterExpression = this.filterConditions.join(' AND ');
-    }
-    console.log(params);
+    this.filterConditions.push(`#entity = :entity_value`);
+    this.expressionAttributeNames['#entity'] = 'entityType';
+    this.expressionAttributeValues[':entity_value'] = this.parent.getEntityType();
+    params.FilterExpression = this.filterConditions.join(' AND ');
+
     const result = await this.parent.getClient().send(new QueryCommand(params));
-    return this.parent.getSchema().array().parse(result.Items) as T[];
+    return {items: this.parent.getSchema().array().parse(result.Items) as T[], lastKey: result.LastEvaluatedKey ?? undefined};
   }
 }

package/src/builders/scan-builder.ts

@@ -1,6 +1,8 @@
 import { ScanCommand, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
 import { BetterDDB } from '../betterddb';
 import { getOperatorExpression, Operator } from '../operator';
+import { PaginatedResult } from '../types/paginated-result';
+
 export class ScanBuilder<T> {
   private filters: string[] = [];
   private expressionAttributeNames: Record<string, string> = {};
@@ -58,7 +60,7 @@ export class ScanBuilder<T> {
   /**
    * Executes the scan and returns a Promise that resolves with an array of items.
    */
-  public async execute(): Promise<T[]> {
+  public async execute(): Promise<PaginatedResult<T>> {
     const params: ScanCommandInput = {
       TableName: this.parent.getTableName(),
       ExpressionAttributeNames: this.expressionAttributeNames,
@@ -72,6 +74,7 @@ export class ScanBuilder<T> {
     }
 
     const result = await this.parent.getClient().send(new ScanCommand(params));
-    return this.parent.getSchema().array().parse(result.Items) as T[];
+
+    return {items: this.parent.getSchema().array().parse(result.Items) as T[], lastKey: result.LastEvaluatedKey ?? undefined};
   }
 }

package/src/builders/update-builder.ts

@@ -13,14 +13,11 @@ interface UpdateActions<T> {
 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: TransactWriteItem[] = [];
 
   // Reference to the parent BetterDDB instance and key.
-  constructor(private parent: BetterDDB<T>, private key: Partial<T>, expectedVersion?: number) {
-    this.expectedVersion = expectedVersion;
-  }
+  constructor(private parent: BetterDDB<T>, private key: Partial<T>) {}
 
   // Chainable methods:
   public set(attrs: Partial<T>): this {
@@ -136,29 +133,6 @@ export class UpdateBuilder<T> {
       }
     }
 
-    // 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);

package/src/types/paginated-result.ts

@@ -0,0 +1,4 @@
+export type PaginatedResult<T> = {
+  items: T[];
+  lastKey: Record<string, any> | undefined;
+}

package/test/batch-get.test.ts

@@ -7,7 +7,7 @@ import { KeySchemaElement, AttributeDefinition } from '@aws-sdk/client-dynamodb'
 const TEST_TABLE = "batch-get-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
-const ENTITY_NAME = 'USER';
+const ENTITY_TYPE = 'USER';
 const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
 const SORT_KEY = 'sk';
@@ -44,8 +44,6 @@ const UserSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string().email(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
 });
 
 type User = z.infer<typeof UserSchema>;
@@ -53,13 +51,13 @@ type User = z.infer<typeof UserSchema>;
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: TEST_TABLE,
-  entityName: ENTITY_NAME,
+  entityType: ENTITY_TYPE,
   keys: {
     primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
     sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
   },
   client,
-  autoTimestamps: true,
+  timestamps: true,
 });
 
 beforeAll(async () => {

package/test/create.test.ts

@@ -8,7 +8,7 @@ import { KeySchemaElement, AttributeDefinition } from '@aws-sdk/client-dynamodb'
 const TEST_TABLE = "create-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
-const ENTITY_NAME = 'USER';
+const ENTITY_TYPE = 'USER';
 const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
 const SORT_KEY = 'sk';
@@ -44,8 +44,6 @@ const UserSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string().email(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
 });
 
 type User = z.infer<typeof UserSchema>;
@@ -53,14 +51,14 @@ type User = z.infer<typeof UserSchema>;
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: TEST_TABLE,
-  entityName: ENTITY_NAME,
+  entityType: ENTITY_TYPE,
   keys: {
     primary: { name: "pk", definition: { build: (raw) => `USER#${raw.id}` } },
     sort: { name: "sk", definition: { build: (raw) => `EMAIL#${raw.email}` } },
     gsis: { gsi1: { name: 'gsi1', primary: { name: "gsi1pk", definition: { build: (raw) => "NAME" } }, sort: { name: "gsi1sk", definition: { build: (raw) => `NAME#${raw.name}` } } } },
   },
   client,
-  autoTimestamps: true,
+  timestamps: true,
 });
 
 beforeAll(async () => {

package/test/delete.test.ts

@@ -8,7 +8,7 @@ import { KeySchemaElement, AttributeDefinition, GlobalSecondaryIndex } from '@aw
 const TEST_TABLE = "delete-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
-const ENTITY_NAME = 'USER';
+const ENTITY_TYPE = 'USER';
 const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
 const SORT_KEY = 'sk';
@@ -44,8 +44,6 @@ const UserSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string().email(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
 });
 
 type User = z.infer<typeof UserSchema>;
@@ -53,13 +51,13 @@ type User = z.infer<typeof UserSchema>;
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: TEST_TABLE,
-  entityName: ENTITY_NAME,
+  entityType: ENTITY_TYPE,
   keys: {
     primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
     sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
   },
   client,
-  autoTimestamps: true,
+  timestamps: true,
 });
 
 beforeAll(async () => {

package/test/get.test.ts

@@ -8,7 +8,7 @@ import { KeySchemaElement, AttributeDefinition } from '@aws-sdk/client-dynamodb'
 const TEST_TABLE = "get-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
-const ENTITY_NAME = 'USER';
+const ENTITY_TYPE = 'USER';
 const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
 const SORT_KEY = 'sk';
@@ -46,8 +46,6 @@ const UserSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string().email(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
 });
 
 type User = z.infer<typeof UserSchema>;
@@ -55,13 +53,13 @@ type User = z.infer<typeof UserSchema>;
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: TEST_TABLE,
-  entityName: ENTITY_NAME,
+  entityType: ENTITY_TYPE,
   keys: {
     primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
     sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
   },
   client,
-  autoTimestamps: true,
+  timestamps: true,
 });
 
 beforeAll(async () => {

package/test/query.test.ts

@@ -7,7 +7,7 @@ import { createTestTable, deleteTestTable } from './utils/table-setup';
 const TEST_TABLE = "query-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
-const ENTITY_NAME = 'USER';
+const ENTITY_TYPE = 'USER';
 const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
 const SORT_KEY = 'sk';
@@ -45,8 +45,6 @@ const UserSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string().email(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
 });
 
 type User = z.infer<typeof UserSchema>;
@@ -54,7 +52,7 @@ type User = z.infer<typeof UserSchema>;
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: TEST_TABLE,
-  entityName: ENTITY_NAME,
+  entityType: ENTITY_TYPE,
   keys: {
     primary: { 
       name: PRIMARY_KEY, 
@@ -79,7 +77,7 @@ const userDdb = new BetterDDB({
     }
   },
   client,
-  autoTimestamps: true,
+  timestamps: true,
 });
 
 beforeAll(async () => {
@@ -103,8 +101,8 @@ describe('BetterDDB - Query Operation', () => {
       .filter('name', 'begins_with', 'Alice')
       .limitResults(5)
       .execute();
-    expect(results.length).toBeGreaterThanOrEqual(1);
-    results.forEach(result => {
+    expect(results.items.length).toBeGreaterThanOrEqual(1);
+    results.items.forEach(result => {
       expect(result.name).toMatch(/^Alice/);
     });
   });
@@ -114,8 +112,8 @@ describe('BetterDDB - Query Operation', () => {
       .usingIndex('EmailIndex')
       .limitResults(1)
       .execute();
-    expect(results.length).toEqual(1);
-    results.forEach(result => {
+    expect(results.items.length).toEqual(1);
+    results.items.forEach(result => {
       expect(result.email).toEqual('alice@example.com');
     });
   });
@@ -125,8 +123,8 @@ describe('BetterDDB - Query Operation', () => {
     const results = await userDdb.query({ id: 'user-1' })
       .where('begins_with', { email: 'alice' })
       .execute();
-    expect(results.length).toBeGreaterThanOrEqual(1);
-    results.forEach(result => {
+    expect(results.items.length).toBeGreaterThanOrEqual(1);
+    results.items.forEach(result => {
       expect(result.email).toMatch(/^alice/i);
     });
   });
@@ -135,7 +133,7 @@ describe('BetterDDB - Query Operation', () => {
     const results = await userDdb.query({ id: 'user-1' })
       .where('begins_with', { email: 'bob' })
       .execute();
-    expect(results.length).toEqual(0);
+    expect(results.items.length).toEqual(0);
   });
 
   it('should query items using QueryBuilder with index and additional filter', async () => {
@@ -143,8 +141,8 @@ describe('BetterDDB - Query Operation', () => {
       .usingIndex('EmailIndex')
       .filter('name', 'begins_with', 'Alice')
       .execute();
-    expect(results.length).toBeGreaterThanOrEqual(1);
-    results.forEach(result => {
+    expect(results.items.length).toBeGreaterThanOrEqual(1);
+    results.items.forEach(result => {
       expect(result.email).toEqual('alice@example.com');
       expect(result.name).toMatch(/^Alice/);
     });
@@ -160,8 +158,8 @@ describe('BetterDDB - Query Operation', () => {
         { email: 'alice@example.com' } // Upper bound -> built to "USER#alice@example.com"
       ])
       .execute();
-    expect(results.length).toBeGreaterThanOrEqual(1);
-    results.forEach(result => {
+    expect(results.items.length).toBeGreaterThanOrEqual(1);
+    results.items.forEach(result => {
       // The built sort key for user-1 is "USER#alice@example.com"
       expect(result.email).toMatch(/alice@example\.com/i);
     });
@@ -175,8 +173,8 @@ describe('BetterDDB - Query Operation', () => {
       .filter('name', 'begins_with', 'Alice')
       .filter('name', 'contains', 'B')
       .execute();
-    expect(results.length).toEqual(1);
-    results.forEach(result => {
+    expect(results.items.length).toEqual(1);
+    results.items.forEach(result => {
       expect(result.name).toMatch(/^Alice/);
       expect(result.name).toContain('B');
     });

package/test/scan.test.ts

@@ -7,7 +7,7 @@ import { KeySchemaElement, AttributeDefinition } from '@aws-sdk/client-dynamodb'
 const TEST_TABLE = "scan-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
-const ENTITY_NAME = 'USER';
+const ENTITY_TYPE = 'USER';
 const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
 const SORT_KEY = 'sk';
@@ -44,8 +44,6 @@ const UserSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string().email(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
 });
 
 type User = z.infer<typeof UserSchema>;
@@ -53,13 +51,13 @@ type User = z.infer<typeof UserSchema>;
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: TEST_TABLE,
-  entityName: ENTITY_NAME,
+  entityType: ENTITY_TYPE,
   keys: {
     primary: { name: PRIMARY_KEY, definition: { build: (raw) => `USER#${raw.id}` } },
     sort: { name: SORT_KEY, definition: { build: (raw) => `EMAIL#${raw.email}` } },
   },
   client,
-  autoTimestamps: true,
+  timestamps: true,
 });
 
 beforeAll(async () => {
@@ -82,8 +80,8 @@ describe('BetterDDB - Scan Operation', () => {
     const results = await userDdb.scan()
       .where('email', 'begins_with', 'a')
       .limitResults(10).execute();
-    expect(results.length).toBeGreaterThanOrEqual(1);
-    results.forEach(result => {
+    expect(results.items.length).toBeGreaterThanOrEqual(1);
+    results.items.forEach(result => {
       expect(result.email).toMatch(/^alice/i);
     });
   });
@@ -94,8 +92,8 @@ describe('BetterDDB - Scan Operation', () => {
         .where('name', 'contains', 'Alice')
         .limitResults(10)
         .execute();
-      expect(results.length).toBeGreaterThan(0);
-      results.forEach(result => {
+      expect(results.items.length).toBeGreaterThan(0);
+      results.items.forEach(result => {
       expect(result.name).toContain('Alice');
       });
   });
@@ -106,8 +104,8 @@ describe('BetterDDB - Scan Operation', () => {
     const results = await userDdb.scan()
       .where('email', 'between', ['a', 'c'])
       .execute();
-    expect(results.length).toBeGreaterThan(0);
-    results.forEach(result => {
+    expect(results.items.length).toBeGreaterThan(0);
+    results.items.forEach(result => {
       // A simple lexicographical check
       expect(result.email >= 'a' && result.email <= 'c').toBeTruthy();
     });

package/test/update.test.ts

@@ -7,7 +7,7 @@ import { KeySchemaElement, AttributeDefinition } from '@aws-sdk/client-dynamodb'
 const TEST_TABLE = "update-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
-const ENTITY_NAME = 'USER';
+const ENTITY_TYPE = 'USER';
 const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
 const SORT_KEY = 'sk';
@@ -44,9 +44,6 @@ const UserSchema = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string().email(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-  version: z.number().optional(),
 });
 
 type User = z.infer<typeof UserSchema>;
@@ -54,13 +51,13 @@ type User = z.infer<typeof UserSchema>;
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: TEST_TABLE,
-  entityName: ENTITY_NAME,
+  entityType: ENTITY_TYPE,
   keys: {
     primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
     sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
   },
   client,
-  autoTimestamps: true,
+  timestamps: true,
 });
 
 beforeAll(async () => {