betterddb 0.6.13 → 0.6.14

package/README.md

@@ -164,4 +164,4 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## License
 
-MIT © Ryan Krumholz
+MIT © Ryan Rawlings Wang

package/dist/jest.config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config = {
+    testEnvironment: 'node',
+    roots: ['<rootDir>/test/'],
+    testMatch: ['**/*.test.ts'],
+    transform: {
+        '^.+\\.(ts|tsx|js|jsx)$': 'ts-jest'
+    },
+    moduleNameMapper: {
+        '^@/(.*)$': '<rootDir>/src/$1',
+        '^~/(.*)$': '<rootDir>/src/$1'
+    },
+    extensionsToTreatAsEsm: ['.ts', '.tsx'],
+    moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node']
+};
+exports.default = config;

package/dist/{builders → src/builders}/update-builder.js

@@ -19,6 +19,10 @@ class UpdateBuilder {
         const partialSchema = this.parent.getSchema().partial();
         const validated = partialSchema.parse(attrs);
         this.actions.set = { ...this.actions.set, ...validated };
+        const indexAttributes = this.parent.buildIndexes(validated);
+        if (Object.keys(indexAttributes).length > 0) {
+            this.actions.set = { ...this.actions.set, ...indexAttributes };
+        }
         return this;
     }
     remove(attrs) {
@@ -29,6 +33,10 @@ class UpdateBuilder {
         const partialSchema = this.parent.getSchema().partial();
         const validated = partialSchema.parse(attrs);
         this.actions.add = { ...this.actions.add, ...validated };
+        const indexAttributes = this.parent.buildIndexes(validated);
+        if (Object.keys(indexAttributes).length > 0) {
+            this.actions.set = { ...this.actions.set, ...indexAttributes };
+        }
         return this;
     }
     delete(attrs) {
@@ -38,14 +46,19 @@ class UpdateBuilder {
     /**
      * Adds a condition expression to the update.
      */
-    setCondition(expression, attributeValues) {
+    setCondition(expression, attributeValues, attributeNames) {
         if (this.condition) {
             // Merge conditions with AND.
             this.condition.expression += ` AND ${expression}`;
             Object.assign(this.condition.attributeValues, attributeValues);
+            Object.assign(this.condition.attributeNames, attributeNames);
         }
         else {
-            this.condition = { expression, attributeValues };
+            this.condition = {
+                expression,
+                attributeValues,
+                attributeNames
+            };
         }
         return this;
     }
@@ -119,8 +132,9 @@ class UpdateBuilder {
                 clauses.push(`DELETE ${deleteParts.join(", ")}`);
             }
         }
-        // Merge any provided condition attribute values.
+        // Merge any provided condition attribute names and values
         if (this.condition) {
+            Object.assign(ExpressionAttributeNames, this.condition.attributeNames);
             Object.assign(ExpressionAttributeValues, this.condition.attributeValues);
         }
         if (Object.keys(ExpressionAttributeValues).length === 0) {

package/dist/test/batch-get.test.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const betterddb_1 = require("../src/betterddb");
+const table_setup_1 = require("./utils/table-setup");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const TEST_TABLE = "batch-get-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'sk';
+const SORT_KEY_TYPE = 'S';
+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' }
+];
+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 },
+];
+const GSIS = [
+    {
+        IndexName: GSI_NAME,
+        KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+        Projection: {
+            ProjectionType: 'ALL',
+        },
+    },
+];
+const client = lib_dynamodb_1.DynamoDBDocumentClient.from(new client_dynamodb_1.DynamoDB({
+    region: REGION,
+    endpoint: ENDPOINT,
+}));
+const UserSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    email: zod_1.z.string().email(),
+});
+const userDdb = new betterddb_1.BetterDDB({
+    schema: UserSchema,
+    tableName: TEST_TABLE,
+    entityType: ENTITY_TYPE,
+    keys: {
+        primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id } },
+        sort: { name: SORT_KEY, definition: { build: (raw) => raw.email } },
+    },
+    client,
+    timestamps: true,
+});
+beforeAll(async () => {
+    await (0, table_setup_1.createTestTable)(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
+    await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' }).execute();
+    await userDdb.create({ id: 'user-124', name: 'John Doe', email: 'john@example.com' }).execute();
+    await userDdb.create({ id: 'user-125', name: 'Bob Doe', email: 'bob@example.com' }).execute();
+});
+afterAll(async () => {
+    await (0, table_setup_1.deleteTestTable)(TEST_TABLE);
+});
+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.some(user => user.id === 'user-123')).toBe(true);
+        expect(users.some(user => user.id === 'user-124')).toBe(true);
+    });
+    it('should retrieve an item using GetBuilder that does not exist', async () => {
+        const users = await userDdb.batchGet([{ id: 'user-123', email: 'jane@example.com' }]).execute();
+        expect(users.length).toEqual(0);
+    });
+    it('should return an empty array if no keys are provided', async () => {
+        const users = await userDdb.batchGet([]).execute();
+        expect(users.length).toEqual(0);
+    });
+    it('should deduplicate keys', async () => {
+        const users = await userDdb.batchGet([{ id: 'user-123', email: 'john@example.com' }, { id: 'user-123', email: 'john@example.com' }]).execute();
+        expect(users.length).toEqual(1);
+        expect(users[0].id).toEqual('user-123');
+    });
+});

package/dist/test/create.test.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const betterddb_1 = require("../src/betterddb");
+const table_setup_1 = require("./utils/table-setup");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const lib_dynamodb_2 = require("@aws-sdk/lib-dynamodb");
+const TEST_TABLE = "create-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'sk';
+const SORT_KEY_TYPE = 'S';
+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' }
+];
+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 },
+];
+const GSIS = [
+    {
+        IndexName: GSI_NAME,
+        KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+        Projection: {
+            ProjectionType: 'ALL',
+        },
+    },
+];
+const client = lib_dynamodb_1.DynamoDBDocumentClient.from(new client_dynamodb_1.DynamoDB({
+    region: REGION,
+    endpoint: ENDPOINT,
+}));
+const UserSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    email: zod_1.z.string().email(),
+});
+const userDdb = new betterddb_1.BetterDDB({
+    schema: UserSchema,
+    tableName: TEST_TABLE,
+    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,
+    timestamps: true,
+});
+beforeAll(async () => {
+    await (0, table_setup_1.createTestTable)(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
+});
+afterAll(async () => {
+    await (0, table_setup_1.deleteTestTable)(TEST_TABLE);
+});
+describe('BetterDDB - Create Operation', () => {
+    it('should insert an item using CreateBuilder', async () => {
+        const user = { id: 'user-123', name: 'John Doe', email: 'john@example.com' };
+        await userDdb.create(user).execute();
+        const result = await client.send(new lib_dynamodb_2.GetCommand({ TableName: TEST_TABLE, Key: { pk: 'USER#user-123', sk: 'EMAIL#john@example.com' } }));
+        expect(result).not.toBeNull();
+        expect(result.Item).not.toBeNull();
+        expect(result.Item?.pk).toBe('USER#user-123');
+        expect(result.Item?.sk).toBe('EMAIL#john@example.com');
+        expect(result.Item?.gsi1pk).toBe('NAME');
+        expect(result.Item?.gsi1sk).toBe('NAME#John Doe');
+        expect(result.Item?.id).toBe('user-123');
+        expect(result.Item?.createdAt).not.toBeNull();
+        expect(result.Item?.updatedAt).not.toBeNull();
+    });
+    it('should fails to validate and not insert an item', async () => {
+        const user = { id: 'user-123', email: 'john@example.com' };
+        await expect(userDdb.create(user).execute()).rejects.toThrow();
+    });
+});

package/dist/test/delete.test.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// __tests__/delete.test.ts
+const zod_1 = require("zod");
+const betterddb_1 = require("../src/betterddb");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const table_setup_1 = require("./utils/table-setup");
+const TEST_TABLE = "delete-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'sk';
+const SORT_KEY_TYPE = 'S';
+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' }
+];
+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 },
+];
+const GSIS = [
+    {
+        IndexName: GSI_NAME,
+        KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+        Projection: {
+            ProjectionType: 'ALL',
+        },
+    },
+];
+const client = lib_dynamodb_1.DynamoDBDocumentClient.from(new client_dynamodb_1.DynamoDB({
+    region: REGION,
+    endpoint: ENDPOINT,
+}));
+const UserSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    email: zod_1.z.string().email(),
+});
+const userDdb = new betterddb_1.BetterDDB({
+    schema: UserSchema,
+    tableName: TEST_TABLE,
+    entityType: ENTITY_TYPE,
+    keys: {
+        primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id } },
+        sort: { name: SORT_KEY, definition: { build: (raw) => raw.email } },
+    },
+    client,
+    timestamps: true,
+});
+beforeAll(async () => {
+    await (0, table_setup_1.createTestTable)(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
+    await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' }).execute();
+});
+afterAll(async () => {
+    await (0, table_setup_1.deleteTestTable)(TEST_TABLE);
+});
+describe('BetterDDB - Delete Operation', () => {
+    it('should delete an item using DeleteBuilder', async () => {
+        await userDdb.delete({ id: 'user-123', email: 'john@example.com' })
+            .execute();
+        const deletedUser = await userDdb.get({ id: 'user-123', email: 'john@example.com' }).execute();
+        expect(deletedUser).toBeNull();
+    });
+});

package/dist/test/get.test.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// __tests__/get.test.ts
+const zod_1 = require("zod");
+const betterddb_1 = require("../src/betterddb");
+const table_setup_1 = require("./utils/table-setup");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const TEST_TABLE = "get-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'sk';
+const SORT_KEY_TYPE = 'S';
+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' }
+];
+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 },
+];
+const GSIS = [
+    {
+        IndexName: GSI_NAME,
+        KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+        Projection: {
+            ProjectionType: 'ALL',
+        },
+    },
+];
+const client = lib_dynamodb_1.DynamoDBDocumentClient.from(new client_dynamodb_1.DynamoDB({
+    region: REGION,
+    endpoint: ENDPOINT,
+}));
+const UserSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    email: zod_1.z.string().email(),
+});
+const userDdb = new betterddb_1.BetterDDB({
+    schema: UserSchema,
+    tableName: TEST_TABLE,
+    entityType: ENTITY_TYPE,
+    keys: {
+        primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id } },
+        sort: { name: SORT_KEY, definition: { build: (raw) => raw.email } },
+    },
+    client,
+    timestamps: true,
+});
+beforeAll(async () => {
+    await (0, table_setup_1.createTestTable)(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
+    await userDdb.create({ id: 'user-123', name: 'John Doe', email: 'john@example.com' }).execute();
+});
+afterAll(async () => {
+    await (0, table_setup_1.deleteTestTable)(TEST_TABLE);
+});
+describe('BetterDDB - Get Operation', () => {
+    it('should retrieve an item using GetBuilder', async () => {
+        const user = await userDdb.get({ id: 'user-123', email: 'john@example.com' }).execute();
+        expect(user).not.toBeNull();
+        expect(user?.id).toBe('user-123');
+    });
+    it('should retrieve an item using GetBuilder that does not exist', async () => {
+        const user = await userDdb.get({ id: 'user-123', email: 'jane@example.com' }).execute();
+        expect(user).toBeNull();
+    });
+});

package/dist/test/query.test.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const betterddb_1 = require("../src/betterddb");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const table_setup_1 = require("./utils/table-setup");
+const TEST_TABLE = "query-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'sk';
+const SORT_KEY_TYPE = 'S';
+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' }
+];
+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 },
+];
+const GSIS = [
+    {
+        IndexName: GSI_NAME,
+        KeySchema: [
+            { AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' },
+            { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }
+        ],
+        Projection: { ProjectionType: 'ALL' },
+    },
+];
+const client = lib_dynamodb_1.DynamoDBDocumentClient.from(new client_dynamodb_1.DynamoDB({
+    region: REGION,
+    endpoint: ENDPOINT,
+}));
+const UserSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    email: zod_1.z.string().email(),
+});
+const userDdb = new betterddb_1.BetterDDB({
+    schema: UserSchema,
+    tableName: TEST_TABLE,
+    entityType: ENTITY_TYPE,
+    keys: {
+        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: GSI_PRIMARY_KEY,
+                    definition: { build: (raw) => `USER#${raw.email}` }
+                },
+                sort: {
+                    name: GSI_SORT_KEY,
+                    definition: { build: (raw) => `USER#${raw.email}` }
+                }
+            }
+        }
+    },
+    client,
+    timestamps: true,
+});
+beforeAll(async () => {
+    await (0, table_setup_1.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' }
+    ];
+    await Promise.all(items.map(item => userDdb.create(item).execute()));
+});
+afterAll(async () => {
+    await (0, table_setup_1.deleteTestTable)(TEST_TABLE);
+});
+describe('BetterDDB - Query Operation', () => {
+    it('should query items using QueryBuilder with filter condition', async () => {
+        const results = await userDdb.query({ id: 'user-1' })
+            .filter('name', 'begins_with', 'Alice')
+            .limitResults(5)
+            .execute();
+        expect(results.items.length).toBeGreaterThanOrEqual(1);
+        results.items.forEach(result => {
+            expect(result.name).toMatch(/^Alice/);
+        });
+    });
+    it('should query items using QueryBuilder with index', async () => {
+        const results = await userDdb.query({ email: 'alice@example.com' })
+            .usingIndex('EmailIndex')
+            .limitResults(1)
+            .execute();
+        expect(results.items.length).toEqual(1);
+        results.items.forEach(result => {
+            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.items.length).toBeGreaterThanOrEqual(1);
+        results.items.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.items.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.items.length).toBeGreaterThanOrEqual(1);
+        results.items.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' },
+            { email: 'alice@example.com' } // Upper bound -> built to "USER#alice@example.com"
+        ])
+            .execute();
+        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);
+        });
+    });
+    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.items.length).toEqual(1);
+        results.items.forEach(result => {
+            expect(result.name).toMatch(/^Alice/);
+            expect(result.name).toContain('B');
+        });
+    });
+    it('should query items using QueryBuilder with where clause 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')
+            .where('begins_with', { email: 'alice' })
+            .execute();
+        expect(results.items.length).toEqual(2);
+    });
+});

package/dist/test/scan.test.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const betterddb_1 = require("../src/betterddb");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const table_setup_1 = require("./utils/table-setup");
+const TEST_TABLE = "scan-test-table";
+const ENDPOINT = 'http://localhost:4566';
+const REGION = 'us-east-1';
+const ENTITY_TYPE = 'USER';
+const PRIMARY_KEY = 'pk';
+const PRIMARY_KEY_TYPE = 'S';
+const SORT_KEY = 'sk';
+const SORT_KEY_TYPE = 'S';
+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' }
+];
+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 },
+];
+const GSIS = [
+    {
+        IndexName: GSI_NAME,
+        KeySchema: [{ AttributeName: GSI_PRIMARY_KEY, KeyType: 'HASH' }, { AttributeName: GSI_SORT_KEY, KeyType: 'RANGE' }],
+        Projection: {
+            ProjectionType: 'ALL',
+        },
+    },
+];
+const client = lib_dynamodb_1.DynamoDBDocumentClient.from(new client_dynamodb_1.DynamoDB({
+    region: REGION,
+    endpoint: ENDPOINT,
+}));
+const UserSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    email: zod_1.z.string().email(),
+});
+const userDdb = new betterddb_1.BetterDDB({
+    schema: UserSchema,
+    tableName: TEST_TABLE,
+    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,
+    timestamps: true,
+});
+beforeAll(async () => {
+    await (0, table_setup_1.createTestTable)(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
+    // Insert multiple items.
+    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' }
+    ];
+    await Promise.all(items.map(item => userDdb.create(item).execute()));
+});
+afterAll(async () => {
+    await (0, table_setup_1.deleteTestTable)(TEST_TABLE);
+});
+describe('BetterDDB - Scan Operation', () => {
+    it('should scan items using ScanBuilder', async () => {
+        const results = await userDdb.scan()
+            .where('email', 'begins_with', 'a')
+            .limitResults(10).execute();
+        expect(results.items.length).toBeGreaterThanOrEqual(1);
+        results.items.forEach(result => {
+            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.items.length).toBeGreaterThan(0);
+        results.items.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.items.length).toBeGreaterThan(0);
+        results.items.forEach(result => {
+            // A simple lexicographical check
+            expect(result.email >= 'a' && result.email <= 'c').toBeTruthy();
+        });
+    });
+});