@ftschopp/dynatable-core 1.4.0 → 1.4.2

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## @ftschopp/dynatable-core [1.4.2](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.4.1...@ftschopp/dynatable-core@1.4.2) (2026-05-08)
+
+
+### Bug Fixes
+
+* **core:** throw at dbParams() when Query has no partition-key condition ([#27](https://github.com/ftschopp/dynatable/issues/27)) ([2f93385](https://github.com/ftschopp/dynatable/commit/2f933850677956a198077421eaeb032372d50724)), closes [#8](https://github.com/ftschopp/dynatable/issues/8)
+
+## @ftschopp/dynatable-core [1.4.1](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.4.0...@ftschopp/dynatable-core@1.4.1) (2026-05-08)
+
+
+### Bug Fixes
+
+* **core:** use ExpressionAttributeNames placeholders for projections ([#25](https://github.com/ftschopp/dynatable/issues/25)) ([0e14ebd](https://github.com/ftschopp/dynatable/commit/0e14ebd64cfc58eb2b2353fa7678239bdddb22a6)), closes [#5](https://github.com/ftschopp/dynatable/issues/5)
+
 # @ftschopp/dynatable-core [1.4.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.3.0...@ftschopp/dynatable-core@1.4.0) (2026-05-08)
 
 

package/dist/builders/batch-get/create-batch-get-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-batch-get-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-get/create-batch-get-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM1D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EACzC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC,EAC7C,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,EACD,MAAM,CAAC,EAAE,cAAc,GACtB,eAAe,CAAC,KAAK,CAAC,CA0ExB"}
+{"version":3,"file":"create-batch-get-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/batch-get/create-batch-get-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO1D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EACzC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC,EAC7C,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,EACD,MAAM,CAAC,EAAE,cAAc,GACtB,eAAe,CAAC,KAAK,CAAC,CAgFxB"}

package/dist/builders/batch-get/create-batch-get-builder.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBatchGetBuilder = createBatchGetBuilder;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const shared_1 = require("../shared");
 /**
  * Creates a BatchGetBuilder to retrieve multiple items by their keys.
  *
@@ -36,12 +37,16 @@ function createBatchGetBuilder(requestItems, client, options, logger) {
          * Build the underlying DynamoDB input parameters.
          */
         dbParams() {
-            // Apply projection and consistentRead to all tables
+            // Build the projection once (with #-placeholders so reserved words
+            // like name/date/status/type don't blow up at DynamoDB) and reuse
+            // it per-table.
+            const proj = projection.length > 0 ? (0, shared_1.buildProjectionExpression)(projection.map(String)) : undefined;
             const enhancedRequestItems = Object.entries(requestItems).reduce((acc, [tableName, tableRequest]) => {
                 acc[tableName] = {
                     Keys: tableRequest.Keys,
-                    ...(projection.length > 0 && {
-                        ProjectionExpression: projection.join(', '),
+                    ...(proj && {
+                        ProjectionExpression: proj.ProjectionExpression,
+                        ExpressionAttributeNames: proj.ExpressionAttributeNames,
                     }),
                     ...(isConsistent && { ConsistentRead: true }),
                 };

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

@@ -1 +1 @@
-{"version":3,"file":"create-get-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/get/create-get-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AA0B7D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAC9C,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sBAAsB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;CACvD,EACD,MAAM,CAAC,EAAE,cAAc,GACtB,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAgG7B"}
+{"version":3,"file":"create-get-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/get/create-get-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAC9C,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sBAAsB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;CACvD,EACD,MAAM,CAAC,EAAE,cAAc,GACtB,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAgG7B"}

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

@@ -2,24 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createGetBuilder = createGetBuilder;
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
-/**
- * Builds a ProjectionExpression with proper ExpressionAttributeNames
- * to handle reserved words and special characters.
- */
-function buildProjectionExpression(attrs) {
-    const names = {};
-    const projectionParts = [];
-    attrs.forEach((attr) => {
-        // Use a placeholder for the attribute name to avoid reserved word conflicts
-        const placeholder = `#${attr}`;
-        names[placeholder] = attr;
-        projectionParts.push(placeholder);
-    });
-    return {
-        ProjectionExpression: projectionParts.join(', '),
-        ExpressionAttributeNames: names,
-    };
-}
+const shared_1 = require("../shared");
 /**
  * Creates a GetBuilder to retrieve an item by its key.
  */
@@ -68,7 +51,7 @@ function createGetBuilder(tableName, key, client, options, logger) {
             };
             // Add projection with proper ExpressionAttributeNames
             if (projection.length > 0) {
-                const projectionExpr = buildProjectionExpression(projection);
+                const projectionExpr = (0, shared_1.buildProjectionExpression)(projection);
                 params.ProjectionExpression = projectionExpr.ProjectionExpression;
                 params.ExpressionAttributeNames = projectionExpr.ExpressionAttributeNames;
             }

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

@@ -1 +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;AAiX7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY,CAAC,KAAK,CAAC,CA6BrB"}
+{"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;AAM1D,OAAO,EAAE,YAAY,EAA8B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAsZ7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY,CAAC,KAAK,CAAC,CA6BrB"}

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

@@ -4,6 +4,7 @@ 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 projection_1 = require("../shared/projection");
 const model_utils_1 = require("../../utils/model-utils");
 /**
  * Maps a model attribute name to its corresponding DynamoDB key name (PK/SK)
@@ -189,6 +190,25 @@ function createQueryExecutor(state) {
             }
             // Separate key conditions from filter conditions
             const { keyConditions, filterConditions } = separateConditions(state.condition, state.model, state.indexName);
+            // DynamoDB Query requires at least a partition-key condition. If
+            // separation didn't pick anything as a key condition, the caller is
+            // either filtering on non-key attributes (which means they want
+            // scan()) or referencing the wrong attribute name. Fail loudly here
+            // instead of letting the SDK reject the request at execute time.
+            if (keyConditions.length === 0) {
+                const keyTemplates = state.indexName
+                    ? Object.entries(state.model?.index ?? {})
+                        .filter(([keyName]) => keyName.startsWith(state.indexName))
+                        .map(([, def]) => def.value)
+                    : Object.values(state.model?.key ?? {}).map((def) => def.value);
+                const templateVars = Array.from(new Set(keyTemplates.flatMap((tpl) => (0, model_utils_1.extractTemplateVars)(tpl))));
+                const indexHint = state.indexName ? ` on index "${state.indexName}"` : '';
+                const fieldsHint = templateVars.length > 0
+                    ? ` Expected a condition on one of: ${templateVars.join(', ')}.`
+                    : '';
+                throw new Error(`Query requires a condition on the partition key${indexHint}.${fieldsHint} ` +
+                    `For non-key filtering use scan() instead.`);
+            }
             // Build KeyConditionExpression (simple AND)
             const keyExpr = buildSimpleAndExpression(keyConditions);
             // Auto-inject an entity-type filter so query() only returns items
@@ -226,6 +246,16 @@ function createQueryExecutor(state) {
                 ...(keyExpr.values ?? {}),
                 ...(filterExpr.values ?? {}),
             };
+            // Build ProjectionExpression with placeholders so reserved words
+            // (name, date, status, type, …) don't blow up at DynamoDB.
+            // Idempotent merge: filter/key and projection placeholders both map
+            // `#name → name`, so collisions resolve to the same value.
+            let projectionExpression;
+            if (state.projection && state.projection.length > 0) {
+                const proj = (0, projection_1.buildProjectionExpression)(state.projection.map((a) => String(a)));
+                projectionExpression = proj.ProjectionExpression;
+                Object.assign(allNames, proj.ExpressionAttributeNames);
+            }
             return {
                 TableName: state.tableName,
                 ...(keyExpr.expression && {
@@ -245,9 +275,8 @@ function createQueryExecutor(state) {
                 ...(state.scanForward !== undefined && {
                     ScanIndexForward: state.scanForward,
                 }),
-                ...(state.projection &&
-                    state.projection.length > 0 && {
-                    ProjectionExpression: state.projection.join(', '),
+                ...(projectionExpression && {
+                    ProjectionExpression: projectionExpression,
                 }),
                 ...(state.consistentReadEnabled && { ConsistentRead: true }),
                 ...(state.exclusiveStartKey && {

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

@@ -1 +1 @@
-{"version":3,"file":"create-scan-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/scan/create-scan-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAAmB,MAAM,WAAW,CAAC;AACrF,OAAO,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,SAAS,EAAO,EACzB,eAAe,GAAE,CAAC,MAAM,KAAK,CAAC,EAAO,EACrC,UAAU,CAAC,EAAE,MAAM,EACnB,gBAAgB,UAAQ,EACxB,SAAS,CAAC,EAAE,MAAM,EAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvC,aAAa,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAC1D,MAAM,CAAC,EAAE,cAAc,GACtB,WAAW,CAAC,KAAK,CAAC,CAqOpB"}
+{"version":3,"file":"create-scan-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/scan/create-scan-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAGL,SAAS,EAGV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,SAAS,EAAO,EACzB,eAAe,GAAE,CAAC,MAAM,KAAK,CAAC,EAAO,EACrC,UAAU,CAAC,EAAE,MAAM,EACnB,gBAAgB,UAAQ,EACxB,SAAS,CAAC,EAAE,MAAM,EAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACvC,aAAa,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAC1D,MAAM,CAAC,EAAE,cAAc,GACtB,WAAW,CAAC,KAAK,CAAC,CA6OpB"}

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

@@ -54,10 +54,18 @@ function createScanBuilder(tableName, client, filters = [], projectionAttrs = []
                 expressionAttributeNames = result.names;
                 expressionAttributeValues = result.values;
             }
-            // Build ProjectionExpression
+            // Build ProjectionExpression with placeholders so reserved words
+            // (name, date, status, type, …) don't blow up at DynamoDB.
             let projectionExpression = '';
             if (projectionAttrs.length > 0) {
-                projectionExpression = projectionAttrs.map((attr) => String(attr)).join(', ');
+                const proj = (0, shared_1.buildProjectionExpression)(projectionAttrs.map((attr) => String(attr)));
+                projectionExpression = proj.ProjectionExpression;
+                // Idempotent merge: filter and projection placeholders both map
+                // `#name → name`, so collisions resolve to the same value.
+                expressionAttributeNames = {
+                    ...proj.ExpressionAttributeNames,
+                    ...expressionAttributeNames,
+                };
             }
             const params = {
                 TableName: tableName,

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

@@ -1,4 +1,5 @@
 export * from './types';
 export * from './operators';
 export * from './conditions';
+export * from './projection';
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/builders/shared/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./operators"), exports);
 __exportStar(require("./conditions"), exports);
+__exportStar(require("./projection"), exports);

package/dist/builders/shared/projection.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Builds a `ProjectionExpression` together with the matching
+ * `ExpressionAttributeNames` map so that any attribute — including
+ * DynamoDB reserved words like `name`, `date`, `status`, `type`, `data`,
+ * `count`, `size`, `value`, `time`, `year`, `source`, … — is referenced
+ * via a `#placeholder`.
+ *
+ * Without this indirection DynamoDB rejects the request with
+ * `ValidationException: Attribute name is a reserved keyword`.
+ */
+export declare function buildProjectionExpression(attrs: string[]): {
+    ProjectionExpression: string;
+    ExpressionAttributeNames: Record<string, string>;
+};
+//# sourceMappingURL=projection.d.ts.map

package/dist/builders/shared/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../src/builders/shared/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG;IAC1D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD,CAcA"}

package/dist/builders/shared/projection.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProjectionExpression = buildProjectionExpression;
+/**
+ * Builds a `ProjectionExpression` together with the matching
+ * `ExpressionAttributeNames` map so that any attribute — including
+ * DynamoDB reserved words like `name`, `date`, `status`, `type`, `data`,
+ * `count`, `size`, `value`, `time`, `year`, `source`, … — is referenced
+ * via a `#placeholder`.
+ *
+ * Without this indirection DynamoDB rejects the request with
+ * `ValidationException: Attribute name is a reserved keyword`.
+ */
+function buildProjectionExpression(attrs) {
+    const names = {};
+    const projectionParts = [];
+    attrs.forEach((attr) => {
+        const placeholder = `#${attr}`;
+        names[placeholder] = attr;
+        projectionParts.push(placeholder);
+    });
+    return {
+        ProjectionExpression: projectionParts.join(', '),
+        ExpressionAttributeNames: names,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-core",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Core library for DynamoDB single table design",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/builders/batch-get/create-batch-get-builder.test.ts

@@ -64,7 +64,12 @@ describe('BatchGetBuilder', () => {
               { pk: 'USER#alice', sk: 'USER#alice' },
               { pk: 'USER#bob', sk: 'USER#bob' },
             ],
-            ProjectionExpression: 'username, name, followerCount',
+            ProjectionExpression: '#username, #name, #followerCount',
+            ExpressionAttributeNames: {
+              '#username': 'username',
+              '#name': 'name',
+              '#followerCount': 'followerCount',
+            },
           },
         },
       });
@@ -155,11 +160,34 @@ describe('BatchGetBuilder', () => {
               { pk: 'USER#alice', sk: 'USER#alice' },
               { pk: 'USER#bob', sk: 'USER#bob' },
             ],
-            ProjectionExpression: 'username, name',
+            ProjectionExpression: '#username, #name',
+            ExpressionAttributeNames: {
+              '#username': 'username',
+              '#name': 'name',
+            },
             ConsistentRead: true,
           },
         },
       });
     });
+
+    test('reserved DynamoDB words like "name", "date", "status" can be projected', () => {
+      const requestItems = {
+        Users: {
+          Keys: [{ pk: 'USER#alice', sk: 'USER#alice' }],
+        },
+      };
+
+      const builder = createBatchGetBuilder<User>(requestItems, client).select(['name']);
+      const params = builder.dbParams();
+
+      expect(params.RequestItems!['Users']).toEqual({
+        Keys: [{ pk: 'USER#alice', sk: 'USER#alice' }],
+        ProjectionExpression: '#name',
+        ExpressionAttributeNames: {
+          '#name': 'name',
+        },
+      });
+    });
   });
 });

package/src/builders/batch-get/create-batch-get-builder.ts

@@ -5,6 +5,7 @@ import {
   BatchGetCommandInput,
   BatchGetCommandOutput,
 } from '@aws-sdk/lib-dynamodb';
+import { buildProjectionExpression } from '../shared';
 import { BatchGetBuilder } from './types';
 import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 
@@ -63,13 +64,19 @@ export function createBatchGetBuilder<Model>(
      * Build the underlying DynamoDB input parameters.
      */
     dbParams(): BatchGetCommandInput {
-      // Apply projection and consistentRead to all tables
+      // Build the projection once (with #-placeholders so reserved words
+      // like name/date/status/type don't blow up at DynamoDB) and reuse
+      // it per-table.
+      const proj =
+        projection.length > 0 ? buildProjectionExpression(projection.map(String)) : undefined;
+
       const enhancedRequestItems = Object.entries(requestItems).reduce(
         (acc, [tableName, tableRequest]) => {
           acc[tableName] = {
             Keys: tableRequest.Keys,
-            ...(projection.length > 0 && {
-              ProjectionExpression: projection.join(', '),
+            ...(proj && {
+              ProjectionExpression: proj.ProjectionExpression,
+              ExpressionAttributeNames: proj.ExpressionAttributeNames,
             }),
             ...(isConsistent && { ConsistentRead: true }),
           };

package/src/builders/get/create-get-builder.ts

@@ -1,33 +1,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { GetCommand, GetCommandInput, GetCommandOutput } from '@aws-sdk/lib-dynamodb';
+import { buildProjectionExpression } from '../shared';
 import { GetBuilder } from './types';
 import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 
-/**
- * Builds a ProjectionExpression with proper ExpressionAttributeNames
- * to handle reserved words and special characters.
- */
-function buildProjectionExpression(attrs: string[]): {
-  ProjectionExpression: string;
-  ExpressionAttributeNames: Record<string, string>;
-} {
-  const names: Record<string, string> = {};
-  const projectionParts: string[] = [];
-
-  attrs.forEach((attr) => {
-    // Use a placeholder for the attribute name to avoid reserved word conflicts
-    const placeholder = `#${attr}`;
-    names[placeholder] = attr;
-    projectionParts.push(placeholder);
-  });
-
-  return {
-    ProjectionExpression: projectionParts.join(', '),
-    ExpressionAttributeNames: names,
-  };
-}
-
 /**
  * Creates a GetBuilder to retrieve an item by its key.
  */

package/src/builders/query/create-query-builder.test.ts

@@ -12,8 +12,9 @@ describe('QueryBuilder - Pagination', () => {
   const tableName = 'TestTable';
 
   interface TestModel {
-    pk: string;
-    sk: string;
+    PK: string;
+    SK: string;
+    username: string;
     name?: string;
     age?: number;
     status?: string;
@@ -38,9 +39,9 @@ describe('QueryBuilder - Pagination', () => {
 
   describe('startFrom method', () => {
     test('should add ExclusiveStartKey to query params', () => {
-      const startKey = { pk: 'USER#alice', sk: 'USER#alice' };
+      const startKey = { PK: 'USER#alice', SK: 'USER#alice' };
       const params = createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .where((attr, op) => op.eq(attr.username, 'alice'))
         .startFrom(startKey)
         .dbParams();
 
@@ -48,9 +49,9 @@ describe('QueryBuilder - Pagination', () => {
     });
 
     test('should work with all other query options', () => {
-      const startKey = { pk: 'USER#alice', sk: 'USER#alice' };
+      const startKey = { PK: 'USER#alice', SK: 'USER#alice' };
       const params = createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .where((attr, op) => op.eq(attr.username, 'alice'))
         .startFrom(startKey)
         .limit(10)
         .scanIndexForward(false)
@@ -60,12 +61,18 @@ describe('QueryBuilder - Pagination', () => {
       expect(params.ExclusiveStartKey).toEqual(startKey);
       expect(params.Limit).toBe(10);
       expect(params.ScanIndexForward).toBe(false);
-      expect(params.ProjectionExpression).toBe('name, age');
+      expect(params.ProjectionExpression).toBe('#name, #age');
+      expect(params.ExpressionAttributeNames).toEqual(
+        expect.objectContaining({
+          '#name': 'name',
+          '#age': 'age',
+        })
+      );
     });
 
     test('should not include ExclusiveStartKey if not set', () => {
       const params = createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .where((attr, op) => op.eq(attr.username, 'alice'))
         .dbParams();
 
       expect(params.ExclusiveStartKey).toBeUndefined();
@@ -75,10 +82,10 @@ describe('QueryBuilder - Pagination', () => {
   describe('executeWithPagination method', () => {
     test('should return items and lastEvaluatedKey', async () => {
       const mockItems = [
-        { pk: 'USER#alice', sk: 'USER#alice', name: 'Alice' },
-        { pk: 'USER#bob', sk: 'USER#bob', name: 'Bob' },
+        { PK: 'USER#alice', SK: 'USER#alice', name: 'Alice' },
+        { PK: 'USER#bob', SK: 'USER#bob', name: 'Bob' },
       ];
-      const mockLastKey = { pk: 'USER#bob', sk: 'USER#bob' };
+      const mockLastKey = { PK: 'USER#bob', SK: 'USER#bob' };
 
       ddbMock.on(QueryCommand).resolves({
         Items: mockItems,
@@ -88,7 +95,7 @@ describe('QueryBuilder - Pagination', () => {
       });
 
       const result = await createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .where((attr, op) => op.eq(attr.username, 'alice'))
         .limit(2)
         .executeWithPagination();
 
@@ -99,7 +106,7 @@ describe('QueryBuilder - Pagination', () => {
     });
 
     test('should return undefined lastEvaluatedKey when no more results', async () => {
-      const mockItems = [{ pk: 'USER#alice', sk: 'USER#alice', name: 'Alice' }];
+      const mockItems = [{ PK: 'USER#alice', SK: 'USER#alice', name: 'Alice' }];
 
       ddbMock.on(QueryCommand).resolves({
         Items: mockItems,
@@ -108,7 +115,7 @@ describe('QueryBuilder - Pagination', () => {
       });
 
       const result = await createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.eq(attr.pk, 'USER#alice'))
+        .where((attr, op) => op.eq(attr.username, 'alice'))
         .executeWithPagination();
 
       expect(result.items).toEqual(mockItems);
@@ -123,7 +130,7 @@ describe('QueryBuilder - Pagination', () => {
       });
 
       const result = await createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.eq(attr.pk, 'USER#nonexistent'))
+        .where((attr, op) => op.eq(attr.username, 'nonexistent'))
         .executeWithPagination();
 
       expect(result.items).toEqual([]);
@@ -137,20 +144,20 @@ describe('QueryBuilder - Pagination', () => {
     test('should support manual pagination loop', async () => {
       // First page
       const page1Items = [
-        { pk: 'USER#1', sk: 'USER#1', name: 'User 1' },
-        { pk: 'USER#2', sk: 'USER#2', name: 'User 2' },
+        { PK: 'USER#1', SK: 'USER#1', name: 'User 1' },
+        { PK: 'USER#2', SK: 'USER#2', name: 'User 2' },
       ];
-      const page1LastKey = { pk: 'USER#2', sk: 'USER#2' };
+      const page1LastKey = { PK: 'USER#2', SK: 'USER#2' };
 
       // Second page
       const page2Items = [
-        { pk: 'USER#3', sk: 'USER#3', name: 'User 3' },
-        { pk: 'USER#4', sk: 'USER#4', name: 'User 4' },
+        { PK: 'USER#3', SK: 'USER#3', name: 'User 3' },
+        { PK: 'USER#4', SK: 'USER#4', name: 'User 4' },
       ];
-      const page2LastKey = { pk: 'USER#4', sk: 'USER#4' };
+      const page2LastKey = { PK: 'USER#4', SK: 'USER#4' };
 
       // Third page (last)
-      const page3Items = [{ pk: 'USER#5', sk: 'USER#5', name: 'User 5' }];
+      const page3Items = [{ PK: 'USER#5', SK: 'USER#5', name: 'User 5' }];
 
       ddbMock
         .on(QueryCommand)
@@ -177,7 +184,7 @@ describe('QueryBuilder - Pagination', () => {
 
       // Page 1
       const result1 = await createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .where((attr, op) => op.beginsWith(attr.username, ''))
         .limit(2)
         .executeWithPagination();
 
@@ -187,7 +194,7 @@ describe('QueryBuilder - Pagination', () => {
 
       // Page 2
       const result2 = await createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .where((attr, op) => op.beginsWith(attr.username, ''))
         .limit(2)
         .startFrom(lastKey)
         .executeWithPagination();
@@ -198,7 +205,7 @@ describe('QueryBuilder - Pagination', () => {
 
       // Page 3
       const result3 = await createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .where((attr, op) => op.beginsWith(attr.username, ''))
         .limit(2)
         .startFrom(lastKey)
         .executeWithPagination();
@@ -214,13 +221,77 @@ describe('QueryBuilder - Pagination', () => {
     });
   });
 
+  describe('requires a partition-key condition', () => {
+    test('throws when where() only references non-key attributes', () => {
+      const builder = createQueryBuilder<TestModel>(tableName, client, testModel).where(
+        (attr, op) => op.eq(attr.status, 'active')
+      );
+
+      expect(() => builder.dbParams()).toThrow(/partition key/i);
+    });
+
+    test('error message lists the available key field names from the model', () => {
+      const builder = createQueryBuilder<TestModel>(tableName, client, testModel).where(
+        (attr, op) => op.eq(attr.status, 'active')
+      );
+
+      expect(() => builder.dbParams()).toThrow(/username/);
+    });
+
+    test('error message points users at scan() as the alternative', () => {
+      const builder = createQueryBuilder<TestModel>(tableName, client, testModel).where(
+        (attr, op) => op.eq(attr.status, 'active')
+      );
+
+      expect(() => builder.dbParams()).toThrow(/scan\(\)/);
+    });
+
+    test('error message references the index name when querying a GSI', () => {
+      const modelWithIndex: ModelDefinition = {
+        key: {
+          PK: { type: String, value: 'USER#${username}' },
+          SK: { type: String, value: 'USER#${username}' },
+        },
+        index: {
+          GSI1PK: { type: String, value: 'EMAIL#${email}' },
+          GSI1SK: { type: String, value: 'USER#${username}' },
+        },
+        attributes: {
+          username: { type: String, required: true },
+          email: { type: String, required: true },
+          status: { type: String },
+        },
+      };
+
+      const builder = createQueryBuilder<TestModel & { email: string }>(
+        tableName,
+        client,
+        modelWithIndex
+      )
+        .where((attr, op) => op.eq(attr.status, 'active'))
+        .useIndex('GSI1');
+
+      expect(() => builder.dbParams()).toThrow(/GSI1/);
+      // The hint should mention the GSI's template vars, not the table's.
+      expect(() => builder.dbParams()).toThrow(/email/);
+    });
+
+    test('does NOT throw when the where condition matches a key template variable', () => {
+      const builder = createQueryBuilder<TestModel>(tableName, client, testModel).where(
+        (attr, op) => op.eq(attr.username, 'alice')
+      );
+
+      expect(() => builder.dbParams()).not.toThrow();
+    });
+  });
+
   describe('Immutability', () => {
     test('should create new builder instance when using startFrom', () => {
       const builder1 = createQueryBuilder<TestModel>(tableName, client, testModel).where(
-        (attr, op) => op.eq(attr.pk, 'USER#alice')
+        (attr, op) => op.eq(attr.username, 'alice')
       );
 
-      const startKey = { pk: 'USER#alice', sk: 'USER#alice' };
+      const startKey = { PK: 'USER#alice', SK: 'USER#alice' };
       const builder2 = builder1.startFrom(startKey);
 
       expect(builder1.dbParams().ExclusiveStartKey).toBeUndefined();
@@ -231,24 +302,24 @@ describe('QueryBuilder - Pagination', () => {
   describe('iterate method', () => {
     test('walks every page transparently and yields items in order', async () => {
       const page1 = [
-        { pk: 'USER#1', sk: 'USER#1', name: 'User 1' },
-        { pk: 'USER#2', sk: 'USER#2', name: 'User 2' },
+        { PK: 'USER#1', SK: 'USER#1', name: 'User 1' },
+        { PK: 'USER#2', SK: 'USER#2', name: 'User 2' },
       ];
       const page2 = [
-        { pk: 'USER#3', sk: 'USER#3', name: 'User 3' },
-        { pk: 'USER#4', sk: 'USER#4', name: 'User 4' },
+        { PK: 'USER#3', SK: 'USER#3', name: 'User 3' },
+        { PK: 'USER#4', SK: 'USER#4', name: 'User 4' },
       ];
-      const page3 = [{ pk: 'USER#5', sk: 'USER#5', name: 'User 5' }];
+      const page3 = [{ PK: 'USER#5', SK: 'USER#5', name: 'User 5' }];
 
       ddbMock
         .on(QueryCommand)
-        .resolvesOnce({ Items: page1, LastEvaluatedKey: { pk: 'USER#2', sk: 'USER#2' } })
-        .resolvesOnce({ Items: page2, LastEvaluatedKey: { pk: 'USER#4', sk: 'USER#4' } })
+        .resolvesOnce({ Items: page1, LastEvaluatedKey: { PK: 'USER#2', SK: 'USER#2' } })
+        .resolvesOnce({ Items: page2, LastEvaluatedKey: { PK: 'USER#4', SK: 'USER#4' } })
         .resolvesOnce({ Items: page3 });
 
       const collected: TestModel[] = [];
       for await (const item of createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .where((attr, op) => op.beginsWith(attr.username, ''))
         .iterate()) {
         collected.push(item);
       }
@@ -265,17 +336,17 @@ describe('QueryBuilder - Pagination', () => {
     });
 
     test('forwards ExclusiveStartKey from each response into the next call', async () => {
-      const cursor1 = { pk: 'USER#2', sk: 'USER#2' };
-      const cursor2 = { pk: 'USER#4', sk: 'USER#4' };
+      const cursor1 = { PK: 'USER#2', SK: 'USER#2' };
+      const cursor2 = { PK: 'USER#4', SK: 'USER#4' };
 
       ddbMock
         .on(QueryCommand)
-        .resolvesOnce({ Items: [{ pk: 'USER#1', sk: 'USER#1' }], LastEvaluatedKey: cursor1 })
-        .resolvesOnce({ Items: [{ pk: 'USER#3', sk: 'USER#3' }], LastEvaluatedKey: cursor2 })
-        .resolvesOnce({ Items: [{ pk: 'USER#5', sk: 'USER#5' }] });
+        .resolvesOnce({ Items: [{ PK: 'USER#1', SK: 'USER#1' }], LastEvaluatedKey: cursor1 })
+        .resolvesOnce({ Items: [{ PK: 'USER#3', SK: 'USER#3' }], LastEvaluatedKey: cursor2 })
+        .resolvesOnce({ Items: [{ PK: 'USER#5', SK: 'USER#5' }] });
 
       const iterator = createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .where((attr, op) => op.beginsWith(attr.username, ''))
         .iterate();
 
       // Consume the iterator
@@ -292,12 +363,12 @@ describe('QueryBuilder - Pagination', () => {
     });
 
     test('starts from the user-provided cursor on the first call', async () => {
-      const startKey = { pk: 'USER#10', sk: 'USER#10' };
+      const startKey = { PK: 'USER#10', SK: 'USER#10' };
 
-      ddbMock.on(QueryCommand).resolves({ Items: [{ pk: 'USER#11', sk: 'USER#11' }] });
+      ddbMock.on(QueryCommand).resolves({ Items: [{ PK: 'USER#11', SK: 'USER#11' }] });
 
       const iterator = createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .where((attr, op) => op.beginsWith(attr.username, ''))
         .startFrom(startKey)
         .iterate();
 
@@ -315,15 +386,15 @@ describe('QueryBuilder - Pagination', () => {
         .on(QueryCommand)
         .resolvesOnce({
           Items: [
-            { pk: 'USER#1', sk: 'USER#1', name: 'User 1' },
-            { pk: 'USER#2', sk: 'USER#2', name: 'User 2' },
+            { PK: 'USER#1', SK: 'USER#1', name: 'User 1' },
+            { PK: 'USER#2', SK: 'USER#2', name: 'User 2' },
           ],
-          LastEvaluatedKey: { pk: 'USER#2', sk: 'USER#2' },
+          LastEvaluatedKey: { PK: 'USER#2', SK: 'USER#2' },
         });
 
       const collected: TestModel[] = [];
       for await (const item of createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.beginsWith(attr.pk, 'USER#'))
+        .where((attr, op) => op.beginsWith(attr.username, ''))
         .iterate()) {
         collected.push(item);
         if (collected.length >= 1) break;
@@ -338,7 +409,7 @@ describe('QueryBuilder - Pagination', () => {
 
       const collected: TestModel[] = [];
       for await (const item of createQueryBuilder<TestModel>(tableName, client, testModel)
-        .where((attr, op) => op.beginsWith(attr.pk, 'NONE#'))
+        .where((attr, op) => op.eq(attr.username, 'nonexistent'))
         .iterate()) {
         collected.push(item);
       }
@@ -622,3 +693,78 @@ describe('QueryBuilder - entity type auto filter', () => {
     expect(params.ExpressionAttributeValues?.[':_type']).toBe('AirportPersonnel');
   });
 });
+
+describe('QueryBuilder - projection placeholders', () => {
+  const client = new DynamoDBClient({});
+  const tableName = 'TestTable';
+
+  interface UserModel {
+    PK: string;
+    SK: string;
+    username: string;
+    name?: string;
+    status?: string;
+    age?: number;
+    type?: string;
+  }
+
+  const userModel: ModelDefinition = {
+    key: {
+      PK: { type: String, value: 'USER#${username}' },
+      SK: { type: String, value: 'USER#${username}' },
+    },
+    attributes: {
+      username: { type: String, required: true },
+      name: { type: String },
+      status: { type: String },
+      age: { type: Number },
+      type: { type: String },
+    },
+  };
+
+  test('projects reserved DynamoDB words via #-placeholders', () => {
+    const params = createQueryBuilder<UserModel>(tableName, client, userModel)
+      .where((attr, op) => op.eq(attr.username, 'alice'))
+      .select(['name', 'status', 'type'])
+      .dbParams();
+
+    expect(params.ProjectionExpression).toBe('#name, #status, #type');
+    expect(params.ExpressionAttributeNames).toEqual(
+      expect.objectContaining({
+        '#name': 'name',
+        '#status': 'status',
+        '#type': 'type',
+      })
+    );
+  });
+
+  test('merges projection names with key/filter names without clobbering', () => {
+    const params = createQueryBuilder<UserModel>(tableName, client, userModel)
+      .where((attr, op) => op.and(op.eq(attr.username, 'alice'), op.gt(attr.age, 18)))
+      .select(['name', 'status'])
+      .dbParams();
+
+    // Projection placeholders (#name, #status) merged with key (#PK from
+    // the username→PK template rewrite) and filter (#age) — none clobbered.
+    expect(params.ExpressionAttributeNames).toEqual(
+      expect.objectContaining({
+        '#name': 'name',
+        '#status': 'status',
+        '#PK': 'PK',
+        '#age': 'age',
+      })
+    );
+  });
+
+  test('shares the same placeholder when an attribute is both projected and filtered (no key duplication)', () => {
+    const params = createQueryBuilder<UserModel>(tableName, client, userModel)
+      .where((attr, op) => op.and(op.eq(attr.username, 'alice'), op.eq(attr.status, 'active')))
+      .select(['name', 'status'])
+      .dbParams();
+
+    // The map has #status exactly once, mapping to "status".
+    expect(params.ExpressionAttributeNames!['#status']).toBe('status');
+    expect(params.ProjectionExpression).toBe('#name, #status');
+    expect(params.FilterExpression).toMatch(/#status = :status_\d+/);
+  });
+});

package/src/builders/query/create-query-builder.ts

@@ -4,6 +4,7 @@ import { QueryCommand, QueryCommandInput } from '@aws-sdk/lib-dynamodb';
 import { Condition, AttrBuilder, AttrRef } from '../shared';
 import { createOpBuilder } from '../shared/operators';
 import { buildExpression } from '../shared/conditions';
+import { buildProjectionExpression } from '../shared/projection';
 import { QueryBuilder, QueryExecutor, QueryResult } from './types';
 import { ModelDefinition } from '../../core/types';
 import { extractTemplateVars } from '../../utils/model-utils';
@@ -263,6 +264,31 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
         state.indexName
       );
 
+      // DynamoDB Query requires at least a partition-key condition. If
+      // separation didn't pick anything as a key condition, the caller is
+      // either filtering on non-key attributes (which means they want
+      // scan()) or referencing the wrong attribute name. Fail loudly here
+      // instead of letting the SDK reject the request at execute time.
+      if (keyConditions.length === 0) {
+        const keyTemplates = state.indexName
+          ? Object.entries(state.model?.index ?? {})
+              .filter(([keyName]) => keyName.startsWith(state.indexName!))
+              .map(([, def]) => def.value)
+          : Object.values(state.model?.key ?? {}).map((def) => def.value);
+        const templateVars = Array.from(
+          new Set(keyTemplates.flatMap((tpl) => extractTemplateVars(tpl)))
+        );
+        const indexHint = state.indexName ? ` on index "${state.indexName}"` : '';
+        const fieldsHint =
+          templateVars.length > 0
+            ? ` Expected a condition on one of: ${templateVars.join(', ')}.`
+            : '';
+        throw new Error(
+          `Query requires a condition on the partition key${indexHint}.${fieldsHint} ` +
+            `For non-key filtering use scan() instead.`
+        );
+      }
+
       // Build KeyConditionExpression (simple AND)
       const keyExpr = buildSimpleAndExpression(keyConditions);
 
@@ -294,7 +320,7 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
       }
 
       // Merge attribute names and values from both expressions
-      const allNames = {
+      const allNames: Record<string, string> = {
         ...(keyExpr.names ?? {}),
         ...(filterExpr.names ?? {}),
       };
@@ -303,6 +329,19 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
         ...(filterExpr.values ?? {}),
       };
 
+      // Build ProjectionExpression with placeholders so reserved words
+      // (name, date, status, type, …) don't blow up at DynamoDB.
+      // Idempotent merge: filter/key and projection placeholders both map
+      // `#name → name`, so collisions resolve to the same value.
+      let projectionExpression: string | undefined;
+      if (state.projection && state.projection.length > 0) {
+        const proj = buildProjectionExpression(
+          (state.projection as (keyof Model)[]).map((a) => String(a))
+        );
+        projectionExpression = proj.ProjectionExpression;
+        Object.assign(allNames, proj.ExpressionAttributeNames);
+      }
+
       return {
         TableName: state.tableName,
         ...(keyExpr.expression && {
@@ -322,10 +361,9 @@ function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Mod
         ...(state.scanForward !== undefined && {
           ScanIndexForward: state.scanForward,
         }),
-        ...(state.projection &&
-          state.projection.length > 0 && {
-            ProjectionExpression: state.projection.join(', '),
-          }),
+        ...(projectionExpression && {
+          ProjectionExpression: projectionExpression,
+        }),
         ...(state.consistentReadEnabled && { ConsistentRead: true }),
         ...(state.exclusiveStartKey && {
           ExclusiveStartKey: state.exclusiveStartKey,

package/src/builders/scan/create-scan-builder.test.ts

@@ -77,17 +77,52 @@ describe('ScanBuilder', () => {
         .select(['name', 'age', 'status'])
         .dbParams();
 
-      expect(params.ProjectionExpression).toBe('name, age, status');
+      expect(params.ProjectionExpression).toBe('#name, #age, #status');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#age': 'age',
+        '#status': 'status',
+      });
     });
 
-    test('should build params with select and filter', () => {
+    test('should build params with select and filter, merging ExpressionAttributeNames', () => {
       const params = createScanBuilder<TestModel>(tableName, client)
         .select(['name', 'age'])
-        .filter((attr, op) => op.gt(attr.age, 18))
+        .filter((attr, op) => op.gt(attr.score, 50))
         .dbParams();
 
-      expect(params.ProjectionExpression).toBe('name, age');
-      expect(params.FilterExpression).toMatch(/#age > :age_\d+/);
+      expect(params.ProjectionExpression).toBe('#name, #age');
+      expect(params.FilterExpression).toMatch(/#score > :score_\d+/);
+      // Merged names from filter (#score) + projection (#name, #age)
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#age': 'age',
+        '#score': 'score',
+      });
+    });
+
+    test('placeholders survive when projected attribute is also referenced in the filter (no key collision)', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .select(['name', 'age'])
+        .filter((attr, op) => op.eq(attr.name, 'alice'))
+        .dbParams();
+
+      expect(params.ProjectionExpression).toBe('#name, #age');
+      // #name resolves to "name" — filter and projection share the placeholder.
+      expect(params.ExpressionAttributeNames!['#name']).toBe('name');
+      expect(params.ExpressionAttributeNames!['#age']).toBe('age');
+    });
+
+    test('reserved DynamoDB words like "name", "date", "status", "type" can be projected', () => {
+      const params = createScanBuilder<TestModel>(tableName, client)
+        .select(['name', 'status'])
+        .dbParams();
+
+      expect(params.ProjectionExpression).toBe('#name, #status');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#status': 'status',
+      });
     });
   });
 
@@ -184,7 +219,7 @@ describe('ScanBuilder', () => {
 
       expect(params.TableName).toBe(tableName);
       expect(params.FilterExpression).toMatch(/\(#age > :age_\d+\) AND \(#status = :status_\d+\)/);
-      expect(params.ProjectionExpression).toBe('name, age, status');
+      expect(params.ProjectionExpression).toBe('#name, #age, #status');
       expect(params.Limit).toBe(100);
       expect(params.ConsistentRead).toBe(true);
       expect(params.IndexName).toBe('GSI1');

package/src/builders/scan/create-scan-builder.ts

@@ -1,7 +1,13 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { ScanCommand } from '@aws-sdk/lib-dynamodb';
-import { buildExpression, AttrBuilder, Condition, createOpBuilder } from '../shared';
+import {
+  buildExpression,
+  AttrBuilder,
+  Condition,
+  createOpBuilder,
+  buildProjectionExpression,
+} from '../shared';
 import { ScanBuilder, ScanResult } from './types';
 import { DynamoDBLogger } from '../../utils/dynamodb-logger';
 
@@ -155,10 +161,18 @@ export function createScanBuilder<Model>(
         expressionAttributeValues = result.values;
       }
 
-      // Build ProjectionExpression
+      // Build ProjectionExpression with placeholders so reserved words
+      // (name, date, status, type, …) don't blow up at DynamoDB.
       let projectionExpression = '';
       if (projectionAttrs.length > 0) {
-        projectionExpression = projectionAttrs.map((attr) => String(attr)).join(', ');
+        const proj = buildProjectionExpression(projectionAttrs.map((attr) => String(attr)));
+        projectionExpression = proj.ProjectionExpression;
+        // Idempotent merge: filter and projection placeholders both map
+        // `#name → name`, so collisions resolve to the same value.
+        expressionAttributeNames = {
+          ...proj.ExpressionAttributeNames,
+          ...expressionAttributeNames,
+        };
       }
 
       const params: any = {

package/src/builders/shared/index.ts

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './operators';
 export * from './conditions';
+export * from './projection';

package/src/builders/shared/projection.ts

@@ -0,0 +1,28 @@
+/**
+ * Builds a `ProjectionExpression` together with the matching
+ * `ExpressionAttributeNames` map so that any attribute — including
+ * DynamoDB reserved words like `name`, `date`, `status`, `type`, `data`,
+ * `count`, `size`, `value`, `time`, `year`, `source`, … — is referenced
+ * via a `#placeholder`.
+ *
+ * Without this indirection DynamoDB rejects the request with
+ * `ValidationException: Attribute name is a reserved keyword`.
+ */
+export function buildProjectionExpression(attrs: string[]): {
+  ProjectionExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+} {
+  const names: Record<string, string> = {};
+  const projectionParts: string[] = [];
+
+  attrs.forEach((attr) => {
+    const placeholder = `#${attr}`;
+    names[placeholder] = attr;
+    projectionParts.push(placeholder);
+  });
+
+  return {
+    ProjectionExpression: projectionParts.join(', '),
+    ExpressionAttributeNames: names,
+  };
+}

package/tests/integration/instagram-clone.integration.test.ts

@@ -346,7 +346,14 @@ describe('Should test dbParams function builder', () => {
       .dbParams();
 
     expect(params.TableName).toBe('InstagramClone');
-    expect(params.ProjectionExpression).toBe('photoId, url, likesCount');
+    expect(params.ProjectionExpression).toBe('#photoId, #url, #likesCount');
+    expect(params.ExpressionAttributeNames).toEqual(
+      expect.objectContaining({
+        '#photoId': 'photoId',
+        '#url': 'url',
+        '#likesCount': 'likesCount',
+      })
+    );
   });
 
   test('Query Likes by photoId', async () => {
@@ -786,9 +793,16 @@ describe('Should test dbParams function builder', () => {
       .select(['username', 'photoId', 'likesCount'])
       .dbParams();
 
-    expect(params.ProjectionExpression).toBe('username, photoId, likesCount');
+    expect(params.ProjectionExpression).toBe('#username, #photoId, #likesCount');
     expect(params.FilterExpression).toBe('#_type = :_type');
     expect(params.ExpressionAttributeValues).toMatchObject({ ':_type': 'Photo' });
+    expect(params.ExpressionAttributeNames).toEqual(
+      expect.objectContaining({
+        '#username': 'username',
+        '#photoId': 'photoId',
+        '#likesCount': 'likesCount',
+      })
+    );
   });
 
   test('SCAN Photos with limit', async () => {
@@ -838,7 +852,7 @@ describe('Should test dbParams function builder', () => {
     expect(params.FilterExpression).toMatch(/size\(#content\) > :content_size_\d+/);
     expect(params.FilterExpression).toMatch(/#_type = :_type/);
     expect(params.ExpressionAttributeValues).toMatchObject({ ':_type': 'Comment' });
-    expect(params.ProjectionExpression).toBe('photoId, commentId, content');
+    expect(params.ProjectionExpression).toBe('#photoId, #commentId, #content');
     expect(params.Limit).toBe(50);
   });
 
@@ -872,7 +886,12 @@ describe('Should test dbParams function builder', () => {
           { PK: 'USER#alice', SK: 'USER#alice' },
           { PK: 'USER#bob', SK: 'USER#bob' },
         ],
-        ProjectionExpression: 'username, name, followerCount',
+        ProjectionExpression: '#username, #name, #followerCount',
+        ExpressionAttributeNames: {
+          '#username': 'username',
+          '#name': 'name',
+          '#followerCount': 'followerCount',
+        },
       },
     });
   });