betterddb 0.4.8 → 0.5.0

package/src/builders/query-builder.ts

@@ -1,17 +1,19 @@
 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 filters: string[] = [];
+  private keyConditions: string[] = [];
+  private filterConditions: string[] = [];
   private expressionAttributeNames: Record<string, string> = {};
   private expressionAttributeValues: Record<string, any> = {};
   private index?: GSIConfig<T>;
-  private sortKeyCondition?: string;
   private limit?: number;
   private lastKey?: Record<string, any>;
   private ascending: boolean = true;
 
-  constructor(private parent: BetterDDB<T>, private key: Partial<T>) {}
+  constructor(private parent: BetterDDB<T>, private key: Partial<T>, ) {}
 
   public usingIndex(indexName: string): this {
     if (!this.parent.getKeys().gsis) {
@@ -36,34 +38,87 @@ export class QueryBuilder<T> {
   }
 
   public where(
+    operator: Operator,
+    values: Partial<T> | [Partial<T>, Partial<T>]
+  ): this {
+    const keys = this.parent.getKeys();
+    // Determine the sort key name from either the index or the primary keys.
+    const sortKeyName = this.index ? this.index.sort?.name : keys.sort?.name;
+    if (!sortKeyName) {
+      throw new Error('Sort key is not defined for this table/index.');
+    }
+    const nameKey = '#sk';
+    this.expressionAttributeNames[nameKey] = sortKeyName;
+    
+    // Enforce that a complex sort key requires an object input.
+    if (typeof values !== 'object' || values === null) {
+      throw new Error(`For complex sort keys, please provide an object with all necessary properties.`);
+    }
+    
+    if (operator === 'between') {
+      if (!Array.isArray(values) || values.length !== 2) {
+        throw new Error(`For 'between' operator, values must be a tuple of two objects`);
+      }
+      const valueKeyStart = ':sk_start';
+      const valueKeyEnd = ':sk_end';
+      // Use the key definition's build function to build the key from the full object.
+      this.expressionAttributeValues[valueKeyStart] = this.index
+        ? this.parent.buildIndexes(values[0])[sortKeyName]
+        : this.parent.buildKey(values[0])[sortKeyName];
+      this.expressionAttributeValues[valueKeyEnd] = this.index
+        ? this.parent.buildIndexes(values[1])[sortKeyName]
+        : this.parent.buildKey(values[1])[sortKeyName];
+      this.keyConditions.push(`${nameKey} BETWEEN ${valueKeyStart} AND ${valueKeyEnd}`);
+    } else if (operator === 'begins_with') {
+      const valueKey = ':sk_value';
+      this.expressionAttributeValues[valueKey] = this.index
+        ? this.parent.buildIndexes(values as Partial<T>)[sortKeyName]
+        : this.parent.buildKey(values as Partial<T>)[sortKeyName];
+      this.keyConditions.push(`begins_with(${nameKey}, ${valueKey})`);
+    } else {
+      // For eq, lt, lte, gt, gte:
+      const valueKey = ':sk_value';
+      this.expressionAttributeValues[valueKey] = this.index
+        ? this.parent.buildIndexes(values as Partial<T>)[sortKeyName]
+        : this.parent.buildKey(values as Partial<T>)[sortKeyName];
+      const condition = getOperatorExpression(operator, nameKey, valueKey);
+      this.keyConditions.push(condition);
+    }
+    return this;
+  }
+  
+
+
+
+  public filter(
     attribute: keyof T,
-    operator: 'eq' | 'begins_with' | 'between',
+    operator: Operator,
     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') {
+    const randomString = Math.random().toString(36).substring(2, 15);
+    const placeholderName = `#attr_${attrStr}_${randomString}`;
+    this.expressionAttributeNames[placeholderName] = attrStr;
+    if (operator === 'between') {
       if (!Array.isArray(values) || values.length !== 2) {
-        throw new Error(`For 'between' operator, values must be a tuple of two items`);
+        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}`);
+      const placeholderValueStart = `:val_start_${attrStr}_${randomString}`;
+      const placeholderValueEnd = `:val_end_${attrStr}_${randomString}`;
+      this.expressionAttributeValues[placeholderValueStart] = values[0];
+      this.expressionAttributeValues[placeholderValueEnd] = values[1];
+      this.filterConditions.push(`${placeholderName} BETWEEN ${placeholderValueStart} AND ${placeholderValueEnd}`);
+    } else if (operator === 'begins_with' || operator === 'contains') {
+      const placeholderValue = `:val_${attrStr}_${randomString}`;
+      this.expressionAttributeValues[placeholderValue] = values;
+      this.filterConditions.push(`${operator}(${placeholderName}, ${placeholderValue})`);
     } else {
-      throw new Error(`Unsupported operator: ${operator}`);
+      const placeholderValue = `:val_${attrStr}_${randomString}`;
+      this.expressionAttributeValues[placeholderValue] = values;
+      const condition = getOperatorExpression(operator, placeholderName, placeholderValue);
+      this.filterConditions.push(condition);
     }
+
     return this;
   }
 
@@ -80,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>;
@@ -88,14 +143,13 @@ export class QueryBuilder<T> {
       pkName = this.index.primary.name;
       builtKey = this.parent.buildIndexes(this.key);
     }
-    this.expressionAttributeNames['#pk'] = pkName;
-
-    let keyConditionExpression = `#pk = :pk_value`;
-    if (this.sortKeyCondition) {
-      keyConditionExpression += ` AND ${this.sortKeyCondition}`;
+    if (!this.expressionAttributeNames['#pk']) {
+      this.expressionAttributeNames['#pk'] = pkName;
+      this.expressionAttributeValues[':pk_value'] = builtKey[pkName];
+      this.keyConditions.unshift(`#pk = :pk_value`);
     }
 
-    this.expressionAttributeValues[':pk_value'] = builtKey[pkName];
+    const keyConditionExpression = this.keyConditions.join(' AND ');
 
     const params: QueryCommandInput = {
       TableName: this.parent.getTableName(),
@@ -105,14 +159,15 @@ export class QueryBuilder<T> {
       ScanIndexForward: this.ascending,
       Limit: this.limit,
       ExclusiveStartKey: this.lastKey,
-      IndexName: this.index?.name ?? undefined
+      IndexName: this.index?.name ?? undefined,
     };
 
-    if (this.filters.length > 0) {
-      params.FilterExpression = this.filters.join(' AND ');
-    }
+    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,5 +1,7 @@
 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[] = [];
@@ -12,32 +14,35 @@ export class ScanBuilder<T> {
 
   public where(
     attribute: keyof T,
-    operator: 'eq' | 'begins_with' | 'between',
+    operator: Operator,
     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 (operator === 'between') {
       if (!Array.isArray(values) || values.length !== 2) {
-        throw new Error(`For 'between' operator, values must be a tuple of two items`);
+        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}`);
+      this.filters.push(
+        `${nameKey} BETWEEN ${valueKeyStart} AND ${valueKeyEnd}`
+      );
+    } else if (operator === 'begins_with' || operator === 'contains') {
+      const valueKey = `:val_${attrStr}`;
+      this.expressionAttributeValues[valueKey] = values;
+      this.filters.push(`${operator}(${nameKey}, ${valueKey})`);
     } else {
-      throw new Error(`Unsupported operator: ${operator}`);
+      const valueKey = `:val_${attrStr}`;
+      this.expressionAttributeValues[valueKey] = values;
+      const condition = getOperatorExpression(operator, nameKey, valueKey);
+      this.filters.push(condition);
     }
     return this;
   }
@@ -55,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,
@@ -69,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/operator.ts

@@ -0,0 +1,43 @@
+export type Operator =
+  | '=='
+  | '!='
+  | '<'
+  | '<='
+  | '>'
+  | '>='
+  | 'begins_with'
+  | 'between'
+  | 'contains';
+
+export function getOperatorExpression(
+  operator: Operator,
+  nameKey: string,
+  valueKey: string,
+  secondValueKey?: string
+): string {
+  switch (operator) {
+    case '==':
+      return `${nameKey} = ${valueKey}`;
+    case '!=':
+      return `${nameKey} <> ${valueKey}`;
+    case '<':
+      return `${nameKey} < ${valueKey}`;
+    case '<=':
+      return `${nameKey} <= ${valueKey}`;
+    case '>':
+      return `${nameKey} > ${valueKey}`;
+    case '>=':
+      return `${nameKey} >= ${valueKey}`;
+    case 'begins_with':
+      return `begins_with(${nameKey}, ${valueKey})`;
+    case 'between':
+      if (!secondValueKey) {
+        throw new Error("The 'between' operator requires two value keys");
+      }
+      return `${nameKey} BETWEEN ${valueKey} AND ${secondValueKey}`;
+    case 'contains':
+      return `contains(${nameKey}, ${valueKey})`;
+    default:
+      throw new Error(`Unsupported operator: ${operator}`);
+  }
+}

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

@@ -2,18 +2,38 @@ import { z } from 'zod';
 import { BetterDDB } from '../src/betterddb';
 import { createTestTable, deleteTestTable } from './utils/table-setup';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { DynamoDB } from '@aws-sdk/client-dynamodb';
+import { DynamoDB, GlobalSecondaryIndex } from '@aws-sdk/client-dynamodb';
 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 PRIMARY_KEY = 'id';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
-const SORT_KEY = 'email';
+const SORT_KEY = 'sk';
 const SORT_KEY_TYPE = 'S';
-const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }] as KeySchemaElement[];
-const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }] as AttributeDefinition[];
+const GSI_NAME = 'EmailIndex';
+const GSI_PRIMARY_KEY = 'gsi1pk';
+const GSI_SORT_KEY = 'gsi1sk';
+const KEY_SCHEMA = [
+  { AttributeName: PRIMARY_KEY, KeyType: 'HASH' },
+  { AttributeName: SORT_KEY, KeyType: 'RANGE' }
+] as KeySchemaElement[];
+const ATTRIBUTE_DEFINITIONS = [
+  { AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE },
+  { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE },
+  { AttributeName: GSI_PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE },
+  { AttributeName: GSI_SORT_KEY, AttributeType: SORT_KEY_TYPE },
+] as AttributeDefinition[];
+const GSIS = [
+  {
+    IndexName: GSI_NAME,
+    KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+    Projection: {
+      ProjectionType: 'ALL',
+    },
+  },
+] as GlobalSecondaryIndex[];
 const client = DynamoDBDocumentClient.from(new DynamoDB({
   region: REGION,
   endpoint: ENDPOINT,
@@ -24,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>;
@@ -33,17 +51,17 @@ 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 () => {
-  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
   await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' } as any).execute();
   await userDdb.create({ id: 'user-124', name: 'John Doe', email: 'john@example.com' } as any).execute();
   await userDdb.create({ id: 'user-125', name: 'Bob Doe', email: 'bob@example.com' } as any).execute();
@@ -57,7 +75,7 @@ describe('BetterDDB - Get Operation', () => {
   it('should retrieve an item using GetBuilder', async () => {
     const users = await userDdb.batchGet([{ id: 'user-123', email: 'john@example.com' }, { id: 'user-124', email: 'john@example.com' }]).execute();
     expect(users.length).toEqual(2);
-    expect(users[0].id).toBe('user-123');
-    expect(users[1].id).toBe('user-124');
+    expect(users.some(user => user.id === 'user-123')).toBe(true);
+    expect(users.some(user => user.id === 'user-124')).toBe(true);
   });
 });

package/test/create.test.ts

@@ -2,19 +2,39 @@ import { z } from 'zod';
 import { BetterDDB } from '../src/betterddb';
 import { createTestTable, deleteTestTable } from './utils/table-setup';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { DynamoDB } from '@aws-sdk/client-dynamodb';
+import { DynamoDB, GlobalSecondaryIndex } from '@aws-sdk/client-dynamodb';
 import { GetCommand } from '@aws-sdk/lib-dynamodb';
 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 PRIMARY_KEY = 'id';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
-const SORT_KEY = 'email';
+const SORT_KEY = 'sk';
 const SORT_KEY_TYPE = 'S';
-const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }] as KeySchemaElement[];
-const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }] as AttributeDefinition[];
+const GSI_NAME = 'EmailIndex';
+const GSI_PRIMARY_KEY = 'gsi1pk';
+const GSI_SORT_KEY = 'gsi1sk';
+const KEY_SCHEMA = [
+  { AttributeName: PRIMARY_KEY, KeyType: 'HASH' },
+  { AttributeName: SORT_KEY, KeyType: 'RANGE' }
+] as KeySchemaElement[];
+const ATTRIBUTE_DEFINITIONS = [
+  { AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE },
+  { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE },
+  { AttributeName: GSI_PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE },
+  { AttributeName: GSI_SORT_KEY, AttributeType: SORT_KEY_TYPE },
+] as AttributeDefinition[];
+const GSIS = [
+  {
+    IndexName: GSI_NAME,
+    KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+    Projection: {
+      ProjectionType: 'ALL',
+    },
+  },
+] as GlobalSecondaryIndex[];
 const client = DynamoDBDocumentClient.from(new DynamoDB({
   region: REGION,
   endpoint: ENDPOINT,
@@ -24,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>;
@@ -33,18 +51,18 @@ 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 () => {
-  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
 });
 
 afterAll(async () => {
@@ -57,7 +75,7 @@ describe('BetterDDB - Create Operation', () => {
 
     await userDdb.create(user as any).execute();
 
-    const result = await client.send(new GetCommand({ TableName: TEST_TABLE, Key: { id: 'user-123', email: 'john@example.com' } }));
+    const result = await client.send(new GetCommand({ TableName: TEST_TABLE, Key: { pk: 'USER#user-123', sk: 'EMAIL#john@example.com' } }));
 
     expect(result).not.toBeNull();
     expect(result.Item).not.toBeNull();

package/test/delete.test.ts

@@ -4,17 +4,37 @@ import { BetterDDB } from '../src/betterddb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import { DynamoDB } from '@aws-sdk/client-dynamodb';
 import { createTestTable, deleteTestTable } from './utils/table-setup';
-import { KeySchemaElement, AttributeDefinition } from '@aws-sdk/client-dynamodb';
+import { KeySchemaElement, AttributeDefinition, GlobalSecondaryIndex } from '@aws-sdk/client-dynamodb';
 const TEST_TABLE = "delete-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
-const ENTITY_NAME = 'USER';
-const PRIMARY_KEY = 'id';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
-const SORT_KEY = 'email';
+const SORT_KEY = 'sk';
 const SORT_KEY_TYPE = 'S';
-const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }] as KeySchemaElement[];
-const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }] as AttributeDefinition[];
+const GSI_NAME = 'EmailIndex';
+const GSI_PRIMARY_KEY = 'gsi1pk';
+const GSI_SORT_KEY = 'gsi1sk';
+const KEY_SCHEMA = [
+  { AttributeName: PRIMARY_KEY, KeyType: 'HASH' },
+  { AttributeName: SORT_KEY, KeyType: 'RANGE' }
+] as KeySchemaElement[];
+const ATTRIBUTE_DEFINITIONS = [
+  { AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE },
+  { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE },
+  { AttributeName: GSI_PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE },
+  { AttributeName: GSI_SORT_KEY, AttributeType: SORT_KEY_TYPE },
+] as AttributeDefinition[];
+const GSIS = [
+  {
+    IndexName: GSI_NAME,
+    KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+    Projection: {
+      ProjectionType: 'ALL',
+    },
+  },
+] as GlobalSecondaryIndex[];
 const client = DynamoDBDocumentClient.from(new DynamoDB({
   region: REGION,
   endpoint: ENDPOINT,
@@ -24,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>;
@@ -33,17 +51,17 @@ 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 () => {
-  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
   await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' } as any).execute();
 });
 

package/test/get.test.ts

@@ -3,18 +3,39 @@ import { z } from 'zod';
 import { BetterDDB } from '../src/betterddb';
 import { createTestTable, deleteTestTable } from './utils/table-setup';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { DynamoDB } from '@aws-sdk/client-dynamodb';
+import { DynamoDB, GlobalSecondaryIndex } from '@aws-sdk/client-dynamodb';
 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 PRIMARY_KEY = 'id';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
 const PRIMARY_KEY_TYPE = 'S';
-const SORT_KEY = 'email';
+const SORT_KEY = 'sk';
 const SORT_KEY_TYPE = 'S';
-const KEY_SCHEMA = [{ AttributeName: PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: SORT_KEY, KeyType: 'RANGE' }] as KeySchemaElement[];
-const ATTRIBUTE_DEFINITIONS = [{ AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE }, { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE }] as AttributeDefinition[];
+const GSI_NAME = 'EmailIndex';
+const GSI_PRIMARY_KEY = 'gsi1pk';
+const GSI_SORT_KEY = 'gsi1sk';
+const KEY_SCHEMA = [
+  { AttributeName: PRIMARY_KEY, KeyType: 'HASH' },
+  { AttributeName: SORT_KEY, KeyType: 'RANGE' }
+] as KeySchemaElement[];
+const ATTRIBUTE_DEFINITIONS = [
+  { AttributeName: PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE },
+  { AttributeName: SORT_KEY, AttributeType: SORT_KEY_TYPE },
+  { AttributeName: GSI_PRIMARY_KEY, AttributeType: PRIMARY_KEY_TYPE },
+  { AttributeName: GSI_SORT_KEY, AttributeType: SORT_KEY_TYPE },
+] as AttributeDefinition[];
+const GSIS = [
+  {
+    IndexName: GSI_NAME,
+    KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+    Projection: {
+      ProjectionType: 'ALL',
+    },
+  },
+] as GlobalSecondaryIndex[];
+
 const client = DynamoDBDocumentClient.from(new DynamoDB({
   region: REGION,
   endpoint: ENDPOINT,
@@ -25,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>;
@@ -34,17 +53,17 @@ 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 () => {
-  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
   await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' } as any).execute();
 });