@ftschopp/dynatable-core 1.0.0

package/dist/builders/get/types.d.ts

@@ -0,0 +1,28 @@
+import { ExecutableBuilder } from '../shared';
+/**
+ * Builder for DynamoDB GetItem operations.
+ * Supports projection, consistent read, and inspection of the final parameters.
+ */
+export interface GetBuilder<KeyInput, Model> extends ExecutableBuilder<Model | undefined> {
+    /**
+     * Adds a projection expression to only return specific attributes.
+     * Returns a new immutable builder.
+     */
+    select(attrs: (keyof Model)[]): GetBuilder<KeyInput, Model>;
+    /**
+     * Enables strongly consistent read (eventual consistency is default).
+     * Returns a new immutable builder.
+     */
+    consistentRead(): GetBuilder<KeyInput, Model>;
+    /**
+     * Configures the ReturnConsumedCapacity parameter.
+     * Returns a new immutable builder.
+     *
+     * @param mode - 'INDEXES' | 'TOTAL' | 'NONE'
+     * - INDEXES: Returns consumed capacity for table and indexes
+     * - TOTAL: Returns total consumed capacity
+     * - NONE: No consumed capacity data returned (default)
+     */
+    returnConsumedCapacity(mode: 'INDEXES' | 'TOTAL' | 'NONE'): GetBuilder<KeyInput, Model>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/builders/get/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/get/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAE,SAAQ,iBAAiB,CAAC,KAAK,GAAG,SAAS,CAAC;IACvF;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,GAAG,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAE5D;;;OAGG;IACH,cAAc,IAAI,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAE9C;;;;;;;;OAQG;IACH,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;CACzF"}

package/dist/builders/get/types.js

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

package/dist/builders/index.d.ts

@@ -0,0 +1,12 @@
+export * from './shared';
+export * from './get';
+export * from './put';
+export * from './query';
+export * from './scan';
+export * from './update';
+export * from './delete';
+export * from './batch-get';
+export * from './batch-write';
+export * from './transact-write';
+export * from './transact-get';
+//# sourceMappingURL=index.d.ts.map

package/dist/builders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AACA,cAAc,UAAU,CAAC;AAGzB,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}

package/dist/builders/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Shared utilities and types
+__exportStar(require("./shared"), exports);
+// Operation builders
+__exportStar(require("./get"), exports);
+__exportStar(require("./put"), exports);
+__exportStar(require("./query"), exports);
+__exportStar(require("./scan"), exports);
+__exportStar(require("./update"), exports);
+__exportStar(require("./delete"), exports);
+__exportStar(require("./batch-get"), exports);
+__exportStar(require("./batch-write"), exports);
+__exportStar(require("./transact-write"), exports);
+__exportStar(require("./transact-get"), exports);

package/dist/builders/put/create-put-builder.d.ts

@@ -0,0 +1,9 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { Condition } from '../shared';
+import { PutBuilder } from './types';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+/**
+ * Creates a PutBuilder for an item and table.
+ */
+export declare function createPutBuilder<Model>(tableName: string, item: Model, client: DynamoDBClient, prevConditions?: Condition[], shouldCheckNotExists?: boolean, returnMode?: 'NONE' | 'ALL_OLD', enableTimestamps?: boolean, logger?: DynamoDBLogger): PutBuilder<Model>;
+//# sourceMappingURL=create-put-builder.d.ts.map

package/dist/builders/put/create-put-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-put-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/put/create-put-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAAmB,MAAM,WAAW,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAgB7D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,KAAK,EACX,MAAM,EAAE,cAAc,EACtB,cAAc,GAAE,SAAS,EAAO,EAChC,oBAAoB,UAAQ,EAC5B,UAAU,GAAE,MAAM,GAAG,SAAkB,EACvC,gBAAgB,UAAQ,EACxB,MAAM,CAAC,EAAE,cAAc,GACtB,UAAU,CAAC,KAAK,CAAC,CAqHnB"}

package/dist/builders/put/create-put-builder.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPutBuilder = createPutBuilder;
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const shared_1 = require("../shared");
+/**
+ * Utility to infer if attribute exists in the item and returns condition.
+ */
+function buildNotExistsConditions(item) {
+    // Check for common key names (both uppercase and lowercase)
+    const possibleKeys = ['PK', 'SK', 'pk', 'sk'];
+    const foundKeys = possibleKeys.filter((key) => key in item);
+    return foundKeys.map((key) => ({
+        expression: `attribute_not_exists(#${key})`,
+        names: { [`#${key}`]: key },
+    }));
+}
+/**
+ * Creates a PutBuilder for an item and table.
+ */
+function createPutBuilder(tableName, item, client, prevConditions = [], shouldCheckNotExists = false, returnMode = 'NONE', enableTimestamps = false, logger) {
+    const conditions = [...prevConditions];
+    const build = () => ({
+        where(fn) {
+            const attrs = new Proxy({}, {
+                get(_, prop) {
+                    return { name: prop };
+                },
+            });
+            // Create a scoped opBuilder for this operation to avoid global state
+            const opBuilder = (0, shared_1.createOpBuilder)();
+            const condition = fn(attrs, opBuilder);
+            return createPutBuilder(tableName, item, client, [...conditions, condition], shouldCheckNotExists, returnMode, enableTimestamps, logger);
+        },
+        ifNotExists() {
+            return createPutBuilder(tableName, item, client, conditions, true, returnMode, enableTimestamps, logger);
+        },
+        returning(mode) {
+            return createPutBuilder(tableName, item, client, conditions, shouldCheckNotExists, mode, enableTimestamps, logger);
+        },
+        dbParams() {
+            let finalConditions = [...conditions];
+            if (shouldCheckNotExists) {
+                finalConditions = [...finalConditions, ...buildNotExistsConditions(item)];
+            }
+            // Add timestamps if enabled
+            let finalItem = item;
+            if (enableTimestamps) {
+                const now = new Date().toISOString();
+                finalItem = {
+                    ...item,
+                    createdAt: now,
+                    updatedAt: now,
+                };
+            }
+            // Build ConditionExpression from condition tree
+            let conditionExpression = '';
+            let expressionAttributeNames = {};
+            let expressionAttributeValues = {};
+            if (finalConditions.length > 0) {
+                // If there's only one condition, use it directly
+                // Otherwise, combine with AND
+                const combinedCondition = finalConditions.length === 1 && finalConditions[0]
+                    ? finalConditions[0]
+                    : {
+                        expression: '',
+                        operator: 'AND',
+                        children: finalConditions,
+                    };
+                const result = (0, shared_1.buildExpression)(combinedCondition);
+                conditionExpression = result.expression;
+                expressionAttributeNames = result.names;
+                expressionAttributeValues = result.values;
+            }
+            const extra = returnMode !== 'NONE' ? { ReturnValues: returnMode } : {};
+            return {
+                TableName: tableName,
+                Item: finalItem,
+                ...(conditionExpression && {
+                    ConditionExpression: conditionExpression,
+                }),
+                ...(Object.keys(expressionAttributeNames).length && {
+                    ExpressionAttributeNames: expressionAttributeNames,
+                }),
+                ...(Object.keys(expressionAttributeValues).length && {
+                    ExpressionAttributeValues: expressionAttributeValues,
+                }),
+                ...extra,
+            };
+        },
+        async execute() {
+            const params = build().dbParams();
+            const response = await client.send(new lib_dynamodb_1.PutCommand(params));
+            logger?.log('PutCommand', params, response);
+            // Return the old item if returnMode is ALL_OLD and it was replaced
+            if (returnMode === 'ALL_OLD' && response.Attributes) {
+                return response.Attributes;
+            }
+            // For NONE mode or when no old item existed, return the new item with timestamps
+            return params.Item;
+        },
+    });
+    return build();
+}

package/dist/builders/put/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './create-put-builder';
+//# sourceMappingURL=index.d.ts.map

package/dist/builders/put/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/put/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC"}

package/dist/builders/put/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./create-put-builder"), exports);

package/dist/builders/put/types.d.ts

@@ -0,0 +1,17 @@
+import { OperationBuilder } from '../shared';
+/**
+ * Builder interface for DynamoDB PutItem operations
+ */
+export interface PutBuilder<Model> extends OperationBuilder<Model> {
+    /**
+     * Adds a condition that the item must not exist (checks pk and sk)
+     */
+    ifNotExists(): PutBuilder<Model>;
+    /**
+     * Configures what values should be returned after the put operation.
+     * - NONE: Nothing is returned (default)
+     * - ALL_OLD: Returns the item as it was before being replaced (if it existed)
+     */
+    returning(mode: 'NONE' | 'ALL_OLD'): PutBuilder<Model>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/builders/put/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/put/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,CAAE,SAAQ,gBAAgB,CAAC,KAAK,CAAC;IAChE;;OAEG;IACH,WAAW,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAEjC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;CACxD"}

package/dist/builders/put/types.js

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

package/dist/builders/query/create-query-builder.d.ts

@@ -0,0 +1,9 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { QueryBuilder } from './types';
+import { ModelDefinition } from '../../core/types';
+import { DynamoDBLogger } from '../../utils/dynamodb-logger';
+/**
+ * Creates a QueryBuilder for a table
+ */
+export declare function createQueryBuilder<Model, M extends ModelDefinition = any>(tableName: string, client: DynamoDBClient, model?: M, logger?: DynamoDBLogger): QueryBuilder<Model, M>;
+//# sourceMappingURL=create-query-builder.d.ts.map

package/dist/builders/query/create-query-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-query-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/query/create-query-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAK1D,OAAO,EAAE,YAAY,EAA8B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAmT7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,CAAC,SAAS,eAAe,GAAG,GAAG,EACvE,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,CAAC,EACT,MAAM,CAAC,EAAE,cAAc,GACtB,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CA4BxB"}

package/dist/builders/query/create-query-builder.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createQueryBuilder = createQueryBuilder;
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const operators_1 = require("../shared/operators");
+const conditions_1 = require("../shared/conditions");
+const model_utils_1 = require("../../utils/model-utils");
+/**
+ * Determines if a field is a key field (used in pk/sk templates)
+ */
+function isKeyField(fieldName, model) {
+    if (!model?.key)
+        return false;
+    const keyEntries = Object.entries(model.key);
+    for (const [, keyDef] of keyEntries) {
+        const templateVars = (0, model_utils_1.extractTemplateVars)(keyDef.value);
+        if (templateVars.includes(fieldName)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Maps a model attribute name to its corresponding DynamoDB key name (PK/SK)
+ * Also returns the key template for value transformation
+ */
+function getKeyNameForAttribute(fieldName, model) {
+    if (!model?.key)
+        return null;
+    for (const [keyName, keyDef] of Object.entries(model.key)) {
+        const templateVars = (0, model_utils_1.extractTemplateVars)(keyDef.value);
+        if (templateVars.includes(fieldName)) {
+            return { keyName, template: keyDef.value }; // Returns "PK" and "UP#${username}"
+        }
+    }
+    return null;
+}
+/**
+ * Apply key template to transform attribute value to key value
+ * e.g., applyKeyTemplate("UP#${username}", "username", "johndoe") -> "UP#johndoe"
+ */
+function applyKeyTemplate(template, fieldName, fieldValue) {
+    return template.replace(`\${${fieldName}}`, fieldValue);
+}
+/**
+ * Separates a condition tree into key conditions and filter conditions
+ * Key conditions are rewritten to use actual DynamoDB key names (PK/SK)
+ */
+function separateConditions(condition, model) {
+    const keyConditions = [];
+    const filterConditions = [];
+    function traverse(cond) {
+        // If it's a combinator
+        if (cond.operator && cond.children) {
+            // For KeyConditionExpression, we can only use AND at the top level
+            if (cond.operator === 'AND') {
+                cond.children.forEach((child) => {
+                    // Check if this is a leaf condition or another combinator
+                    if (child.children) {
+                        // Nested combinator - goes to filter
+                        filterConditions.push(child);
+                    }
+                    else {
+                        traverse(child);
+                    }
+                });
+            }
+            else {
+                // OR at any level must go to filter
+                filterConditions.push(cond);
+            }
+            return;
+        }
+        // It's a leaf condition - check if it's a key field
+        // Extract field name from the expression (e.g., "#username" -> "username")
+        const fieldMatch = cond.expression.match(/#(\w+)/);
+        if (fieldMatch && fieldMatch[1]) {
+            const fieldName = fieldMatch[1];
+            const keyInfo = getKeyNameForAttribute(fieldName, model);
+            if (keyInfo) {
+                // This is a key field - rewrite the condition to use the actual key name
+                // and apply the template to the value
+                // Find the value placeholder in the condition and transform it
+                const newValues = {};
+                if (cond.values) {
+                    for (const [valuePlaceholder, value] of Object.entries(cond.values)) {
+                        // Apply the key template to transform the value
+                        const transformedValue = applyKeyTemplate(keyInfo.template, fieldName, value);
+                        newValues[valuePlaceholder] = transformedValue;
+                    }
+                }
+                const rewrittenCond = {
+                    ...cond,
+                    expression: cond.expression.replace(new RegExp(`#${fieldName}\\b`, 'g'), `#${keyInfo.keyName}`),
+                    names: {
+                        [`#${keyInfo.keyName}`]: keyInfo.keyName,
+                    },
+                    values: newValues,
+                };
+                keyConditions.push(rewrittenCond);
+            }
+            else {
+                filterConditions.push(cond);
+            }
+        }
+        else {
+            // Can't determine field, put in filter to be safe
+            filterConditions.push(cond);
+        }
+    }
+    traverse(condition);
+    return { keyConditions, filterConditions };
+}
+/**
+ * Builds a simple AND expression from multiple conditions
+ */
+function buildSimpleAndExpression(conditions) {
+    if (conditions.length === 0) {
+        return { expression: '', names: {}, values: {} };
+    }
+    const expressions = [];
+    const names = {};
+    const values = {};
+    conditions.forEach((cond) => {
+        expressions.push(cond.expression);
+        Object.assign(names, cond.names || {});
+        Object.assign(values, cond.values || {});
+    });
+    return {
+        expression: expressions.join(' AND '),
+        names,
+        values,
+    };
+}
+/**
+ * Creates the query executor with all query methods
+ */
+function createQueryExecutor(state) {
+    return {
+        limit(count) {
+            return createQueryExecutor({
+                ...state,
+                limitValue: count,
+            });
+        },
+        scanIndexForward(forward) {
+            return createQueryExecutor({
+                ...state,
+                scanForward: forward,
+            });
+        },
+        useIndex(indexName) {
+            return createQueryExecutor({
+                ...state,
+                indexName,
+            });
+        },
+        select(attrs) {
+            return createQueryExecutor({
+                ...state,
+                projection: attrs,
+            });
+        },
+        consistentRead() {
+            return createQueryExecutor({
+                ...state,
+                consistentReadEnabled: true,
+            });
+        },
+        startFrom(key) {
+            return createQueryExecutor({
+                ...state,
+                exclusiveStartKey: key,
+            });
+        },
+        dbParams() {
+            if (!state.condition) {
+                throw new Error('No where condition specified');
+            }
+            // Separate key conditions from filter conditions
+            const { keyConditions, filterConditions } = separateConditions(state.condition, state.model);
+            // Build KeyConditionExpression (simple AND)
+            const keyExpr = buildSimpleAndExpression(keyConditions);
+            // Build FilterExpression (can be complex with OR, NOT, etc.)
+            let filterExpr = { expression: '', names: {}, values: {} };
+            if (filterConditions.length > 0) {
+                if (filterConditions.length === 1 && filterConditions[0]) {
+                    filterExpr = (0, conditions_1.buildExpression)(filterConditions[0]);
+                }
+                else {
+                    // Multiple filter conditions - combine with AND
+                    filterExpr = (0, conditions_1.buildExpression)({
+                        expression: '',
+                        operator: 'AND',
+                        children: filterConditions,
+                    });
+                }
+            }
+            // Merge attribute names and values from both expressions
+            const allNames = {
+                ...(keyExpr.names ?? {}),
+                ...(filterExpr.names ?? {}),
+            };
+            const allValues = {
+                ...(keyExpr.values ?? {}),
+                ...(filterExpr.values ?? {}),
+            };
+            return {
+                TableName: state.tableName,
+                ...(keyExpr.expression && {
+                    KeyConditionExpression: keyExpr.expression,
+                }),
+                ...(filterExpr.expression && {
+                    FilterExpression: filterExpr.expression,
+                }),
+                ...(Object.keys(allNames).length && {
+                    ExpressionAttributeNames: allNames,
+                }),
+                ...(Object.keys(allValues).length && {
+                    ExpressionAttributeValues: allValues,
+                }),
+                ...(state.indexName && { IndexName: state.indexName }),
+                ...(state.limitValue && { Limit: state.limitValue }),
+                ...(state.scanForward !== undefined && {
+                    ScanIndexForward: state.scanForward,
+                }),
+                ...(state.projection &&
+                    state.projection.length > 0 && {
+                    ProjectionExpression: state.projection.join(', '),
+                }),
+                ...(state.consistentReadEnabled && { ConsistentRead: true }),
+                ...(state.exclusiveStartKey && {
+                    ExclusiveStartKey: state.exclusiveStartKey,
+                }),
+            };
+        },
+        async execute() {
+            const params = this.dbParams();
+            const result = await state.client.send(new lib_dynamodb_1.QueryCommand(params));
+            state.logger?.log('QueryCommand', params, result);
+            return (result.Items ?? []);
+        },
+        async executeWithPagination() {
+            const params = this.dbParams();
+            const result = await state.client.send(new lib_dynamodb_1.QueryCommand(params));
+            state.logger?.log('QueryCommand', params, result);
+            return {
+                items: (result.Items ?? []),
+                lastEvaluatedKey: result.LastEvaluatedKey,
+                count: result.Count,
+                scannedCount: result.ScannedCount,
+            };
+        },
+    };
+}
+/**
+ * Creates a QueryBuilder for a table
+ */
+function createQueryBuilder(tableName, client, model, logger) {
+    return {
+        where(fn) {
+            // Create attribute builder proxy
+            const attrProxy = new Proxy({}, {
+                get(_, prop) {
+                    return { name: prop };
+                },
+            });
+            // Create a scoped opBuilder for this query to avoid global state
+            const opBuilder = (0, operators_1.createOpBuilder)();
+            // Call the user's function to get the condition tree
+            const condition = fn(attrProxy, opBuilder);
+            // Create initial state with the condition
+            const initialState = {
+                tableName,
+                client,
+                model,
+                condition,
+                logger,
+            };
+            return createQueryExecutor(initialState);
+        },
+    };
+}

package/dist/builders/query/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './create-query-builder';
+//# sourceMappingURL=index.d.ts.map

package/dist/builders/query/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/query/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC"}

package/dist/builders/query/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./create-query-builder"), exports);

package/dist/builders/query/types.d.ts

@@ -0,0 +1,79 @@
+import { ExecutableBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
+import { ModelDefinition } from '../../core/types';
+/**
+ * Query result with pagination support
+ */
+export interface QueryResult<Model> {
+    /**
+     * The items returned by the query
+     */
+    items: Model[];
+    /**
+     * The LastEvaluatedKey for pagination (if more results available)
+     */
+    lastEvaluatedKey?: Record<string, any>;
+    /**
+     * Number of items examined before applying filters
+     */
+    count?: number;
+    /**
+     * Number of items returned after applying filters
+     */
+    scannedCount?: number;
+}
+/**
+ * Query executor with additional query-specific options
+ */
+export interface QueryExecutor<Model, M extends ModelDefinition = any> extends ExecutableBuilder<Model[]> {
+    /**
+     * Limit the number of items to return
+     */
+    limit(count: number): QueryExecutor<Model, M>;
+    /**
+     * Scan index forward (ascending) or backward (descending)
+     */
+    scanIndexForward(forward: boolean): QueryExecutor<Model, M>;
+    /**
+     * Use a secondary index
+     */
+    useIndex(indexName: string): QueryExecutor<Model, M>;
+    /**
+     * Select specific attributes to return
+     */
+    select(attrs: (keyof Model)[]): QueryExecutor<Model, M>;
+    /**
+     * Use consistent read
+     */
+    consistentRead(): QueryExecutor<Model, M>;
+    /**
+     * Start query from a specific key (for pagination)
+     */
+    startFrom(key: Record<string, any>): QueryExecutor<Model, M>;
+    /**
+     * Returns the raw DynamoDB query parameters
+     */
+    dbParams(): any;
+    /**
+     * Executes the query and returns matching items
+     */
+    execute(): Promise<Model[]>;
+    /**
+     * Executes the query and returns result with pagination metadata
+     */
+    executeWithPagination(): Promise<QueryResult<Model>>;
+}
+/**
+ * Main Query Builder interface with type-safe where clause
+ */
+export interface QueryBuilder<Model, M extends ModelDefinition = any> {
+    /**
+     * Build a condition expression using attributes and operators
+     * Usage: .where((attr, op) => op.eq(attr.username, 'juanca'))
+     * Usage: .where((attr, op) => op.and(
+     *   op.eq(attr.username, 'juanca'),
+     *   op.gt(attr.age, 18)
+     * ))
+     */
+    where(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): QueryExecutor<Model, M>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/builders/query/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/query/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK;IAChC;;OAEG;IACH,KAAK,EAAE,KAAK,EAAE,CAAC;IAEf;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEvC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,EAAE,CAAC,SAAS,eAAe,GAAG,GAAG,CAAE,SAAQ,iBAAiB,CAC9F,KAAK,EAAE,CACR;IACC;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE9C;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE5D;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAErD;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAExD;;OAEG;IACH,cAAc,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE1C;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE7D;;OAEG;IACH,QAAQ,IAAI,GAAG,CAAC;IAEhB;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAE5B;;OAEG;IACH,qBAAqB,IAAI,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,KAAK,EAAE,CAAC,SAAS,eAAe,GAAG,GAAG;IAClE;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;CAC5F"}