@ftschopp/dynatable-core 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## @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;AA6X7D;;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)
@@ -226,6 +227,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 +256,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.1",
   "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

@@ -60,7 +60,13 @@ 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', () => {
@@ -622,3 +628,81 @@ 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;
+    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.pk, 'USER#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 & { username: string }>(
+      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.pk, 'USER#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';
@@ -294,7 +295,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 +304,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 +336,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',
+        },
       },
     });
   });