betterddb 0.4.8 → 0.4.9

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

@@ -1,12 +1,13 @@
 import { BetterDDB } from '../betterddb';
+import { Operator } from '../operator';
 export declare class QueryBuilder<T> {
     private parent;
     private key;
-    private filters;
+    private keyConditions;
+    private filterConditions;
     private expressionAttributeNames;
     private expressionAttributeValues;
     private index?;
-    private sortKeyCondition?;
     private limit?;
     private lastKey?;
     private ascending;
@@ -14,7 +15,8 @@ export declare class QueryBuilder<T> {
     usingIndex(indexName: string): this;
     sortAscending(): this;
     sortDescending(): this;
-    where(attribute: keyof T, operator: 'eq' | 'begins_with' | 'between', values: any | [any, any]): this;
+    where(operator: Operator, values: Partial<T> | [Partial<T>, Partial<T>]): this;
+    filter(attribute: keyof T, operator: Operator, values: any | [any, any]): this;
     limitResults(limit: number): this;
     startFrom(lastKey: Record<string, any>): this;
     /**

package/lib/builders/query-builder.js

@@ -2,11 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryBuilder = void 0;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const operator_1 = require("../operator");
 class QueryBuilder {
     constructor(parent, key) {
         this.parent = parent;
         this.key = key;
-        this.filters = [];
+        this.keyConditions = [];
+        this.filterConditions = [];
         this.expressionAttributeNames = {};
         this.expressionAttributeValues = {};
         this.ascending = true;
@@ -29,32 +31,78 @@ class QueryBuilder {
         this.ascending = false;
         return this;
     }
-    where(attribute, operator, values) {
-        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}`);
+    where(operator, values) {
+        var _a, _b;
+        const keys = this.parent.getKeys();
+        // Determine the sort key name from either the index or the primary keys.
+        const sortKeyName = this.index ? (_a = this.index.sort) === null || _a === void 0 ? void 0 : _a.name : (_b = keys.sort) === null || _b === void 0 ? void 0 : _b.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 = `:val_${attrStr}`;
-            this.expressionAttributeValues[valueKey] = values;
-            this.filters.push(`begins_with(${nameKey}, ${valueKey})`);
+            const valueKey = ':sk_value';
+            this.expressionAttributeValues[valueKey] = this.index
+                ? this.parent.buildIndexes(values)[sortKeyName]
+                : this.parent.buildKey(values)[sortKeyName];
+            this.keyConditions.push(`begins_with(${nameKey}, ${valueKey})`);
         }
-        else if (operator === 'between') {
+        else {
+            // For eq, lt, lte, gt, gte:
+            const valueKey = ':sk_value';
+            this.expressionAttributeValues[valueKey] = this.index
+                ? this.parent.buildIndexes(values)[sortKeyName]
+                : this.parent.buildKey(values)[sortKeyName];
+            const condition = (0, operator_1.getOperatorExpression)(operator, nameKey, valueKey);
+            this.keyConditions.push(condition);
+        }
+        return this;
+    }
+    filter(attribute, operator, values) {
+        const attrStr = String(attribute);
+        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 = (0, operator_1.getOperatorExpression)(operator, placeholderName, placeholderValue);
+            this.filterConditions.push(condition);
         }
         return this;
     }
@@ -78,12 +126,12 @@ class QueryBuilder {
             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 = {
             TableName: this.parent.getTableName(),
             KeyConditionExpression: keyConditionExpression,
@@ -92,11 +140,12 @@ class QueryBuilder {
             ScanIndexForward: this.ascending,
             Limit: this.limit,
             ExclusiveStartKey: this.lastKey,
-            IndexName: (_b = (_a = this.index) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : undefined
+            IndexName: (_b = (_a = this.index) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : undefined,
         };
-        if (this.filters.length > 0) {
-            params.FilterExpression = this.filters.join(' AND ');
+        if (this.filterConditions.length > 0) {
+            params.FilterExpression = this.filterConditions.join(' AND ');
         }
+        console.log(params);
         const result = await this.parent.getClient().send(new lib_dynamodb_1.QueryCommand(params));
         return this.parent.getSchema().array().parse(result.Items);
     }

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

@@ -1,4 +1,5 @@
 import { BetterDDB } from '../betterddb';
+import { Operator } from '../operator';
 export declare class ScanBuilder<T> {
     private parent;
     private filters;
@@ -7,7 +8,7 @@ export declare class ScanBuilder<T> {
     private limit?;
     private lastKey?;
     constructor(parent: BetterDDB<T>);
-    where(attribute: keyof T, operator: 'eq' | 'begins_with' | 'between', values: any | [any, any]): this;
+    where(attribute: keyof T, operator: Operator, values: any | [any, any]): this;
     limitResults(limit: number): this;
     startFrom(lastKey: Record<string, any>): this;
     /**

package/lib/builders/scan-builder.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ScanBuilder = void 0;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const operator_1 = require("../operator");
 class ScanBuilder {
     constructor(parent) {
         this.parent = parent;
@@ -13,17 +14,7 @@ class ScanBuilder {
         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`);
             }
@@ -33,8 +24,16 @@ class ScanBuilder {
             this.expressionAttributeValues[valueKeyEnd] = values[1];
             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 = (0, operator_1.getOperatorExpression)(operator, nameKey, valueKey);
+            this.filters.push(condition);
         }
         return this;
     }

package/lib/operator.d.ts

@@ -0,0 +1,2 @@
+export type Operator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'begins_with' | 'between' | 'contains';
+export declare function getOperatorExpression(operator: Operator, nameKey: string, valueKey: string, secondValueKey?: string): string;

package/lib/operator.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOperatorExpression = void 0;
+function getOperatorExpression(operator, nameKey, valueKey, secondValueKey) {
+    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}`);
+    }
+}
+exports.getOperatorExpression = getOperatorExpression;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "betterddb",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "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/builders/query-builder.ts

@@ -1,17 +1,17 @@
 import { QueryCommand, QueryCommandInput } from '@aws-sdk/lib-dynamodb';
 import { BetterDDB, GSIConfig } from '../betterddb';
-
+import { getOperatorExpression, Operator } from '../operator';
 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 +36,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;
   }
 
@@ -88,14 +141,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,13 +157,13 @@ 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 ');
+    if (this.filterConditions.length > 0) {
+      params.FilterExpression = this.filterConditions.join(' AND ');
     }
-
+    console.log(params);
     const result = await this.parent.getClient().send(new QueryCommand(params));
     return this.parent.getSchema().array().parse(result.Items) as T[];
   }

package/src/builders/scan-builder.ts

@@ -1,6 +1,6 @@
 import { ScanCommand, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
 import { BetterDDB } from '../betterddb';
-
+import { getOperatorExpression, Operator } from '../operator';
 export class ScanBuilder<T> {
   private filters: string[] = [];
   private expressionAttributeNames: Record<string, string> = {};
@@ -12,32 +12,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;
   }

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/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 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,
@@ -43,7 +63,7 @@ const userDdb = new BetterDDB({
 });
 
 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 +77,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 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,
@@ -44,7 +64,7 @@ const userDdb = new BetterDDB({
 });
 
 beforeAll(async () => {
-  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
 });
 
 afterAll(async () => {
@@ -57,7 +77,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 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,
@@ -43,7 +63,7 @@ const userDdb = new BetterDDB({
 });
 
 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 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,
@@ -44,7 +65,7 @@ const userDdb = new BetterDDB({
 });
 
 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/query.test.ts

@@ -1,19 +1,41 @@
 import { z } from 'zod';
 import { BetterDDB } from '../src/betterddb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { AttributeDefinition, DynamoDB, KeySchemaElement } from '@aws-sdk/client-dynamodb';
+import { AttributeDefinition, DynamoDB, GlobalSecondaryIndex, KeySchemaElement } from '@aws-sdk/client-dynamodb';
 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 PRIMARY_KEY = 'id';
+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,
@@ -34,11 +56,25 @@ const userDdb = new BetterDDB({
   tableName: TEST_TABLE,
   entityName: ENTITY_NAME,
   keys: {
-    primary: { name: PRIMARY_KEY, definition: PRIMARY_KEY },
+    primary: { 
+      name: PRIMARY_KEY, 
+      definition: { build: (raw) => `USER#${raw.id}` } 
+    },
+    sort: { 
+      name: SORT_KEY, 
+      definition: { build: (raw) => `USER#${raw.email}` } 
+    },
     gsis: {
       EmailIndex: {
         name: 'EmailIndex',
-        primary: { name: 'email', definition: 'email' }
+        primary: { 
+          name: GSI_PRIMARY_KEY, 
+          definition: { build: (raw) => `USER#${raw.email}` } 
+        },
+        sort: { 
+          name: GSI_SORT_KEY, 
+          definition: { build: (raw) => `USER#${raw.email}` } 
+        }
       }
     }
   },
@@ -47,16 +83,14 @@ const userDdb = new BetterDDB({
 });
 
 beforeAll(async () => {
-  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
 
   const items = [
     { id: 'user-1', name: 'Alice', email: 'alice@example.com' },
     { id: 'user-2', name: 'Alice B', email: 'alice@example.com' },
     { id: 'user-3', name: 'Bob', email: 'bob@example.com' }
   ];
-  for (const item of items) {
-    await userDdb.create(item as any).execute();
-  }
+  await Promise.all(items.map(item => userDdb.create(item as any).execute()));
 });
 
 afterAll(async () => {
@@ -64,10 +98,11 @@ afterAll(async () => {
 });
 
 describe('BetterDDB - Query Operation', () => {
-  it('should query items using QueryBuilder', async () => {
+  it('should query items using QueryBuilder with filter condition', async () => {
     const results = await userDdb.query({ id: 'user-1' })
-      .where('name', 'begins_with', 'Alice')
-      .limitResults(5).execute();
+      .filter('name', 'begins_with', 'Alice')
+      .limitResults(5)
+      .execute();
     expect(results.length).toBeGreaterThanOrEqual(1);
     results.forEach(result => {
       expect(result.name).toMatch(/^Alice/);
@@ -84,4 +119,66 @@ describe('BetterDDB - Query Operation', () => {
       expect(result.email).toEqual('alice@example.com');
     });
   });
+
+  it('should query items using QueryBuilder with a sort key condition', async () => {
+    // For a complex sort key, users must supply an object.
+    const results = await userDdb.query({ id: 'user-1' })
+      .where('begins_with', { email: 'alice' })
+      .execute();
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    results.forEach(result => {
+      expect(result.email).toMatch(/^alice/i);
+    });
+  });
+
+  it('should return no results if the sort key condition does not match', async () => {
+    const results = await userDdb.query({ id: 'user-1' })
+      .where('begins_with', { email: 'bob' })
+      .execute();
+    expect(results.length).toEqual(0);
+  });
+
+  it('should query items using QueryBuilder with index and additional filter', async () => {
+    const results = await userDdb.query({ email: 'alice@example.com' })
+      .usingIndex('EmailIndex')
+      .filter('name', 'begins_with', 'Alice')
+      .execute();
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    results.forEach(result => {
+      expect(result.email).toEqual('alice@example.com');
+      expect(result.name).toMatch(/^Alice/);
+    });
+  });
+
+
+  it('should query items using QueryBuilder with a sort key condition using "between"', async () => {
+    // Here we use the "between" operator. The sort key build function produces a value like "USER#alice@example.com"
+    // We provide lower and upper bounds as objects.
+    const results = await userDdb.query({ id: 'user-1' })
+      .where('between', [
+        { email: 'alice' },          // Lower bound -> built to "USER#alice"
+        { email: 'alice@example.com' } // Upper bound -> built to "USER#alice@example.com"
+      ])
+      .execute();
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    results.forEach(result => {
+      // The built sort key for user-1 is "USER#alice@example.com"
+      expect(result.email).toMatch(/alice@example\.com/i);
+    });
+  });
+
+  it('should query items using QueryBuilder with multiple filter conditions on an index', async () => {
+    // Query the GSI for email "alice@example.com". Two items match.
+    // Then apply two filter conditions: name begins_with "Alice" and name contains "B" should only match one.
+    const results = await userDdb.query({ email: 'alice@example.com' })
+      .usingIndex('EmailIndex')
+      .filter('name', 'begins_with', 'Alice')
+      .filter('name', 'contains', 'B')
+      .execute();
+    expect(results.length).toEqual(1);
+    results.forEach(result => {
+      expect(result.name).toMatch(/^Alice/);
+      expect(result.name).toContain('B');
+    });
+  });
 });

package/test/scan.test.ts

@@ -1,19 +1,39 @@
 import { z } from 'zod';
 import { BetterDDB } from '../src/betterddb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
-import { DynamoDB } from '@aws-sdk/client-dynamodb';
+import { DynamoDB, GlobalSecondaryIndex } from '@aws-sdk/client-dynamodb';
 import { createTestTable, deleteTestTable } from './utils/table-setup';
 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 PRIMARY_KEY = 'id';
+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,
@@ -35,22 +55,22 @@ const userDdb = new BetterDDB({
   tableName: TEST_TABLE,
   entityName: ENTITY_NAME,
   keys: {
-    primary: { name: PRIMARY_KEY, definition: PRIMARY_KEY },
+    primary: { name: PRIMARY_KEY, definition: { build: (raw) => `USER#${raw.id}` } },
+    sort: { name: SORT_KEY, definition: { build: (raw) => `EMAIL#${raw.email}` } },
   },
   client,
   autoTimestamps: true,
 });
 
 beforeAll(async () => {
-  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS);
+  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
   // Insert multiple items.
   const items = [
-    { id: 'user-4', name: 'Charlie', email: 'charlie@example.com' },
-    { id: 'user-5', name: 'Dave', email: 'dave@example.com' }
+    { id: 'user-1', name: 'Alice', email: 'alice@example.com' },
+    { id: 'user-2', name: 'Alice B', email: 'alice@example.com' },
+    { id: 'user-3', name: 'Bob', email: 'bob@example.com' }
   ];
-  for (const item of items) {
-    await userDdb.create(item as any).execute();
-  }
+  await Promise.all(items.map(item => userDdb.create(item as any).execute()));
 });
 
 afterAll(async () => {
@@ -60,11 +80,36 @@ afterAll(async () => {
 describe('BetterDDB - Scan Operation', () => {
   it('should scan items using ScanBuilder', async () => {
     const results = await userDdb.scan()
-      .where('email', 'begins_with', 'char')
+      .where('email', 'begins_with', 'a')
       .limitResults(10).execute();
     expect(results.length).toBeGreaterThanOrEqual(1);
     results.forEach(result => {
-      expect(result.email).toMatch(/^char/i);
+      expect(result.email).toMatch(/^alice/i);
+    });
+  });
+
+  it('should scan items using ScanBuilder with a contains filter', async () => {
+    // Scan for users whose name contains "Alice"
+    const results = await userDdb.scan()
+        .where('name', 'contains', 'Alice')
+        .limitResults(10)
+        .execute();
+      expect(results.length).toBeGreaterThan(0);
+      results.forEach(result => {
+      expect(result.name).toContain('Alice');
+      });
+  });
+
+  it('should scan items using ScanBuilder with a between filter on email', async () => {
+    // Using lexicographical order on the email address:
+    // 'alice@example.com' should be between "a" and "c".
+    const results = await userDdb.scan()
+      .where('email', 'between', ['a', 'c'])
+      .execute();
+    expect(results.length).toBeGreaterThan(0);
+    results.forEach(result => {
+      // A simple lexicographical check
+      expect(result.email >= 'a' && result.email <= 'c').toBeTruthy();
     });
   });
 });

package/test/update.test.ts

@@ -2,18 +2,38 @@ import { z } from 'zod';
 import { BetterDDB } from '../src/betterddb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import { createTestTable, deleteTestTable } from './utils/table-setup';
-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 = "update-test-table";
 const ENDPOINT = 'http://localhost:4566';
 const REGION = 'us-east-1';
 const ENTITY_NAME = 'USER';
-const PRIMARY_KEY = 'id';
+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,
@@ -44,7 +64,7 @@ const userDdb = new BetterDDB({
 });
 
 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/utils/table-setup.ts

@@ -1,6 +1,6 @@
 import { CreateTableCommandInput, DynamoDB } from '@aws-sdk/client-dynamodb';
 
-export const createTestTable = async (tableName: string, keySchema: CreateTableCommandInput['KeySchema'], attributeDefinitions: CreateTableCommandInput['AttributeDefinitions']) => {
+export const createTestTable = async (tableName: string, keySchema: CreateTableCommandInput['KeySchema'], attributeDefinitions: CreateTableCommandInput['AttributeDefinitions'], gsis: CreateTableCommandInput['GlobalSecondaryIndexes']) => {
   const dynamoDB = new DynamoDB({
     region: 'us-east-1',
     endpoint: 'http://localhost:4566',
@@ -14,15 +14,7 @@ export const createTestTable = async (tableName: string, keySchema: CreateTableC
       KeySchema: keySchema,
       AttributeDefinitions: attributeDefinitions,
       BillingMode: 'PAY_PER_REQUEST',
-      GlobalSecondaryIndexes: [
-        {
-          IndexName: 'EmailIndex',
-          KeySchema: [{ AttributeName: 'email', KeyType: 'HASH' }],
-          Projection: {
-            ProjectionType: 'ALL',
-          },
-        },
-      ],
+      GlobalSecondaryIndexes: gsis,
     });
   } catch (error: any) {
     if (error.code === 'ResourceInUseException') {