@ftschopp/dynatable-core 1.0.0 → 1.1.0

package/dist/utils/model-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-utils.d.ts","sourceRoot":"","sources":["../../src/utils/model-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,MAAM,EAG5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAoB7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,eAAe,EACnD,OAAO,CAAC,EACR,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAM,KAAK,GAAG,OAAO,GAAG,MAAc,KACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,eAAe,EACzD,OAAO,CAAC,EACR,eAAe,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,KACrD,UAAU,CAAC,CAAC,CAgCd,CAAC"}
+{"version":3,"file":"model-utils.d.ts","sourceRoot":"","sources":["../../src/utils/model-utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,MAAM,EAG5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAoB7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,eAAe,EACnD,OAAO,CAAC,EACR,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAM,KAAK,GAAG,OAAO,GAAG,MAAc,KACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,eAAe,EACzD,OAAO,CAAC,EACR,eAAe,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,KACrD,UAAU,CAAC,CAAC,CAgCd,CAAC;AAOF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,KAAG,CAAC,GAAG,CAAC,EAAE,GAAG,SAoB1E,CAAC"}

package/dist/utils/model-utils.js

@@ -1,7 +1,7 @@
 "use strict";
 /* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyPostDefaults = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
+exports.stripInternalKeys = exports.applyPostDefaults = exports.resolveKeys = exports.resolveTemplate = exports.extractTemplateVars = void 0;
 const ulid_1 = require("ulid");
 /**
  * Extracts all variable names from a template string
@@ -86,3 +86,31 @@ const applyPostDefaults = (model, validatedItem, options) => {
     return result;
 };
 exports.applyPostDefaults = applyPostDefaults;
+/**
+ * Internal DynamoDB keys that should be stripped when cleanInternalKeys is enabled
+ */
+const INTERNAL_KEYS = ['PK', 'SK', '_type'];
+/**
+ * Removes internal DynamoDB keys from an item or array of items
+ * @param data - Single item or array of items from DynamoDB
+ * @returns Data with internal keys removed
+ */
+const stripInternalKeys = (data) => {
+    if (data === undefined || data === null) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.map((item) => (0, exports.stripInternalKeys)(item));
+    }
+    if (typeof data === 'object') {
+        const cleaned = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (!INTERNAL_KEYS.includes(key)) {
+                cleaned[key] = value;
+            }
+        }
+        return cleaned;
+    }
+    return data;
+};
+exports.stripInternalKeys = stripInternalKeys;

package/dist/utils/zod-utils.d.ts

@@ -1,4 +1,4 @@
-import { AttributeDefinition, ModelDefinition } from '@/core/types';
+import { AttributeDefinition, ModelDefinition } from '../core/types';
 import { ZodObject, ZodType } from 'zod';
 /**
  * Converts an attribute definition to a Zod schema type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Core library for DynamoDB single table design",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc-alias",
     "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
     "test": "jest"
   },
@@ -22,6 +22,7 @@
     "jest": "^30.2.0",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
+    "tsc-alias": "^1.8.16",
     "typescript": "5.9.3"
   },
   "dependencies": {

package/src/builders/README.md

@@ -209,7 +209,33 @@ The `op` parameter in `.where()` provides these operators:
 - `op.gt(attr, value)` - Greater than (>)
 - `op.gte(attr, value)` - Greater than or equal (>=)
 - `op.between(attr, low, high)` - Between two values
-- `op.beginsWith(attr, prefix)` - Begins with a string (for string fields)
+
+**String Operators:**
+
+- `op.beginsWith(attr, prefix)` - Begins with a string prefix (for string/binary fields)
+- `op.contains(attr, value)` - Contains a substring or value (works with strings, sets, and lists)
+
+**Existence Operators:**
+
+- `op.exists(attr)` - Attribute exists
+- `op.notExists(attr)` - Attribute does not exist
+
+**Type Checking:**
+
+- `op.attributeType(attr, type)` - Check the attribute's type
+  - Valid types: `'S'` (String), `'N'` (Number), `'B'` (Binary), `'SS'` (String Set), `'NS'` (Number Set), `'BS'` (Binary Set), `'M'` (Map), `'L'` (List), `'NULL'`, `'BOOL'`
+
+**Advanced Operators:**
+
+- `op.in(attr, values[])` - Attribute value is in the provided array
+- `op.size(attr)` - Get the size of an attribute (string length, number of elements in set/list, etc.)
+  - Returns a `SizeRef` object with comparison methods:
+    - `.eq(n)` - Size equals n
+    - `.ne(n)` - Size not equals n
+    - `.lt(n)` - Size less than n
+    - `.lte(n)` - Size less than or equal to n
+    - `.gt(n)` - Size greater than n
+    - `.gte(n)` - Size greater than or equal to n
 
 **Logical Operators:**
 
@@ -257,6 +283,47 @@ The `op` parameter in `.where()` provides these operators:
 // NOT operator
 .where((attr, op) => op.not(op.eq(attr.status, 'deleted')))
 
+// Existence operators
+.where((attr, op) => op.and(
+  op.eq(attr.username, 'alice'),
+  op.exists(attr.email)              // Has email field
+))
+
+.where((attr, op) => op.notExists(attr.deletedAt))  // Not deleted
+
+// Contains operator (for strings, sets, lists)
+.where((attr, op) => op.and(
+  op.eq(attr.username, 'alice'),
+  op.contains(attr.bio, 'developer')  // Bio contains "developer"
+))
+
+.where((attr, op) => op.contains(attr.tags, 'premium'))  // Has "premium" in tags set/list
+
+// IN operator
+.where((attr, op) => op.in(attr.status, ['active', 'pending', 'verified']))
+
+// Size operator
+.where((attr, op) => op.size(attr.tags).gte(3))        // At least 3 tags
+.where((attr, op) => op.size(attr.username).lt(20))    // Username shorter than 20 chars
+.where((attr, op) => op.size(attr.comments).eq(0))     // No comments
+
+// Attribute type checking
+.where((attr, op) => op.attributeType(attr.metadata, 'M'))  // Is a Map
+.where((attr, op) => op.attributeType(attr.items, 'L'))     // Is a List
+
+// Complex example with new operators
+await table.entities.User.query()
+  .where((attr, op) => op.and(
+    op.eq(attr.status, 'active'),
+    op.exists(attr.email),
+    op.size(attr.followers).gte(10),
+    op.or(
+      op.contains(attr.tags, 'premium'),
+      op.contains(attr.tags, 'verified')
+    )
+  ))
+  .execute();
+
 // Complete example with all features
 await table.entities.Photo.query()
   .where((attr, op) => op.and(

package/src/builders/delete/types.ts

@@ -1,11 +1,17 @@
+import type { DeleteCommandInput } from '@aws-sdk/lib-dynamodb';
 import { OperationBuilder } from '../shared';
 
 /**
  * Builder interface for DynamoDB DeleteItem operations
  */
-export interface DeleteBuilder<Model> extends OperationBuilder<Model> {
+export interface DeleteBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams'> {
   /**
    * Configures what values should be returned after the delete operation
    */
   returning(mode: 'NONE' | 'ALL_OLD'): DeleteBuilder<Model>;
+
+  /**
+   * Converts the builder state to DynamoDB DeleteItem parameters
+   */
+  dbParams(): DeleteCommandInput;
 }

package/src/builders/get/types.ts

@@ -1,10 +1,11 @@
+import type { GetCommandInput } from '@aws-sdk/lib-dynamodb';
 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> {
+export interface GetBuilder<KeyInput, Model> extends Omit<ExecutableBuilder<Model | undefined>, 'dbParams'> {
   /**
    * Adds a projection expression to only return specific attributes.
    * Returns a new immutable builder.
@@ -27,4 +28,9 @@ export interface GetBuilder<KeyInput, Model> extends ExecutableBuilder<Model | u
    * - NONE: No consumed capacity data returned (default)
    */
   returnConsumedCapacity(mode: 'INDEXES' | 'TOTAL' | 'NONE'): GetBuilder<KeyInput, Model>;
+
+  /**
+   * Converts the builder state to DynamoDB GetItem parameters
+   */
+  dbParams(): GetCommandInput;
 }

package/src/builders/put/types.ts

@@ -1,9 +1,10 @@
+import type { PutCommandInput } from '@aws-sdk/lib-dynamodb';
 import { OperationBuilder } from '../shared';
 
 /**
  * Builder interface for DynamoDB PutItem operations
  */
-export interface PutBuilder<Model> extends OperationBuilder<Model> {
+export interface PutBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams'> {
   /**
    * Adds a condition that the item must not exist (checks pk and sk)
    */
@@ -15,4 +16,9 @@ export interface PutBuilder<Model> extends OperationBuilder<Model> {
    * - ALL_OLD: Returns the item as it was before being replaced (if it existed)
    */
   returning(mode: 'NONE' | 'ALL_OLD'): PutBuilder<Model>;
+
+  /**
+   * Converts the builder state to DynamoDB PutItem parameters
+   */
+  dbParams(): PutCommandInput;
 }

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

@@ -181,9 +181,7 @@ function buildSimpleAndExpression(conditions: Condition[]): {
 /**
  * Creates the query executor with all query methods
  */
-function createQueryExecutor<Model, M extends ModelDefinition = any>(
-  state: QueryState<Model>
-): QueryExecutor<Model, M> {
+function createQueryExecutor<Model>(state: QueryState<Model>): QueryExecutor<Model> {
   return {
     limit(count) {
       return createQueryExecutor({
@@ -317,12 +315,12 @@ function createQueryExecutor<Model, M extends ModelDefinition = any>(
 /**
  * Creates a QueryBuilder for a table
  */
-export function createQueryBuilder<Model, M extends ModelDefinition = any>(
+export function createQueryBuilder<Model>(
   tableName: string,
   client: DynamoDBClient,
-  model?: M,
+  model?: ModelDefinition,
   logger?: DynamoDBLogger
-): QueryBuilder<Model, M> {
+): QueryBuilder<Model> {
   return {
     where(fn) {
       // Create attribute builder proxy

package/src/builders/query/types.ts

@@ -1,6 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { ExecutableBuilder, AttrBuilder, OpBuilder, Condition } from '../shared';
-import { ModelDefinition } from '../../core/types';
 
 /**
  * Query result with pagination support
@@ -30,38 +29,36 @@ export interface QueryResult<Model> {
 /**
  * Query executor with additional query-specific options
  */
-export interface QueryExecutor<Model, M extends ModelDefinition = any> extends ExecutableBuilder<
-  Model[]
-> {
+export interface QueryExecutor<Model> extends ExecutableBuilder<Model[]> {
   /**
    * Limit the number of items to return
    */
-  limit(count: number): QueryExecutor<Model, M>;
+  limit(count: number): QueryExecutor<Model>;
 
   /**
    * Scan index forward (ascending) or backward (descending)
    */
-  scanIndexForward(forward: boolean): QueryExecutor<Model, M>;
+  scanIndexForward(forward: boolean): QueryExecutor<Model>;
 
   /**
    * Use a secondary index
    */
-  useIndex(indexName: string): QueryExecutor<Model, M>;
+  useIndex(indexName: string): QueryExecutor<Model>;
 
   /**
    * Select specific attributes to return
    */
-  select(attrs: (keyof Model)[]): QueryExecutor<Model, M>;
+  select(attrs: (keyof Model)[]): QueryExecutor<Model>;
 
   /**
    * Use consistent read
    */
-  consistentRead(): QueryExecutor<Model, M>;
+  consistentRead(): QueryExecutor<Model>;
 
   /**
    * Start query from a specific key (for pagination)
    */
-  startFrom(key: Record<string, any>): QueryExecutor<Model, M>;
+  startFrom(key: Record<string, any>): QueryExecutor<Model>;
 
   /**
    * Returns the raw DynamoDB query parameters
@@ -82,7 +79,7 @@ export interface QueryExecutor<Model, M extends ModelDefinition = any> extends E
 /**
  * Main Query Builder interface with type-safe where clause
  */
-export interface QueryBuilder<Model, M extends ModelDefinition = any> {
+export interface QueryBuilder<Model> {
   /**
    * Build a condition expression using attributes and operators
    * Usage: .where((attr, op) => op.eq(attr.username, 'juanca'))
@@ -91,5 +88,5 @@ export interface QueryBuilder<Model, M extends ModelDefinition = any> {
    *   op.gt(attr.age, 18)
    * ))
    */
-  where(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): QueryExecutor<Model, M>;
+  where(fn: (attr: AttrBuilder<Model>, op: OpBuilder) => Condition): QueryExecutor<Model>;
 }

package/src/builders/transact-write/README.md

@@ -5,9 +5,10 @@ TransactWrite provides atomic multi-item write operations in DynamoDB. All opera
 ## Features
 
 - **Functional API**: Immutable builders using pure functions
-- **Type-safe**: Full TypeScript support
+- **Type-safe**: Full TypeScript support with AWS SDK types
 - **Composable**: Chain operations fluently
 - **Idempotent**: Support for client request tokens
+- **Flexible**: Accepts both entity builder outputs and raw DynamoDB parameters
 
 ## Usage
 
@@ -144,6 +145,41 @@ Use client request tokens for idempotent operations:
 await table.transactWrite().addPut(params).withClientRequestToken('unique-id-12345').execute();
 ```
 
+## Type Safety
+
+All operations are fully typed using AWS SDK types:
+
+```typescript
+import type {
+  TransactPutParams,
+  TransactUpdateParams,
+  TransactDeleteParams,
+  TransactConditionCheckParams,
+} from '@ftschopp/dynatable-core';
+
+// addPut accepts PutCommandInput from @aws-sdk/lib-dynamodb
+const putParams: TransactPutParams = {
+  TableName: 'MyTable',
+  Item: { pk: 'USER#123', sk: 'USER#123', name: 'John' },
+};
+
+// TypeScript validates all parameters at compile time
+table.transactWrite().addPut(putParams).execute();
+```
+
+### Using Entity Builders
+
+Entity builders automatically provide correctly typed parameters via `.dbParams()`:
+
+```typescript
+// The entity builder's dbParams() returns PutCommandInput
+const params = table.entities.User.put({ username: 'john' }).ifNotExists().dbParams();
+// params is typed as PutCommandInput
+
+// Pass it to the transaction builder
+table.transactWrite().addPut(params).execute();
+```
+
 ## Functional Design
 
 The builder is immutable - each method returns a new instance:

package/src/builders/transact-write/create-transact-write-builder.ts

@@ -1,7 +1,13 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { TransactWriteCommand } from '@aws-sdk/lib-dynamodb';
-import { TransactWriteBuilder, TransactWriteState } from './types';
+import {
+  TransactWriteBuilder,
+  TransactWriteState,
+  TransactPutParams,
+  TransactUpdateParams,
+  TransactDeleteParams,
+  TransactConditionCheckParams,
+} from './types';
 
 /**
  * Creates the initial state for a TransactWrite builder
@@ -16,7 +22,7 @@ const createInitialState = (client: DynamoDBClient): TransactWriteState => ({
  */
 const addPutItem =
   (state: TransactWriteState) =>
-  (params: any): TransactWriteState => ({
+  (params: TransactPutParams): TransactWriteState => ({
     ...state,
     items: [...state.items, { Put: params }],
   });
@@ -26,7 +32,7 @@ const addPutItem =
  */
 const addUpdateItem =
   (state: TransactWriteState) =>
-  (params: any): TransactWriteState => ({
+  (params: TransactUpdateParams): TransactWriteState => ({
     ...state,
     items: [...state.items, { Update: params }],
   });
@@ -36,7 +42,7 @@ const addUpdateItem =
  */
 const addDeleteItem =
   (state: TransactWriteState) =>
-  (params: any): TransactWriteState => ({
+  (params: TransactDeleteParams): TransactWriteState => ({
     ...state,
     items: [...state.items, { Delete: params }],
   });
@@ -46,7 +52,7 @@ const addDeleteItem =
  */
 const addConditionCheckItem =
   (state: TransactWriteState) =>
-  (params: any): TransactWriteState => ({
+  (params: TransactConditionCheckParams): TransactWriteState => ({
     ...state,
     items: [...state.items, { ConditionCheck: params }],
   });
@@ -64,9 +70,9 @@ const setClientRequestToken =
 /**
  * Converts the builder state to DynamoDB parameters
  */
-const toDbParams = (state: TransactWriteState) => {
-  const params: any = {
-    TransactItems: state.items,
+const toDbParams = (state: TransactWriteState): ReturnType<TransactWriteBuilder['dbParams']> => {
+  const params: ReturnType<TransactWriteBuilder['dbParams']> = {
+    TransactItems: [...state.items],
   };
 
   if (state.clientRequestToken) {
@@ -89,11 +95,11 @@ const execute = async (state: TransactWriteState) => {
  * Creates a builder from the current state
  */
 const createBuilder = (state: TransactWriteState): TransactWriteBuilder => ({
-  addPut: (params: any) => createBuilder(addPutItem(state)(params)),
-  addUpdate: (params: any) => createBuilder(addUpdateItem(state)(params)),
-  addDelete: (params: any) => createBuilder(addDeleteItem(state)(params)),
-  addConditionCheck: (params: any) => createBuilder(addConditionCheckItem(state)(params)),
-  withClientRequestToken: (token: string) => createBuilder(setClientRequestToken(state)(token)),
+  addPut: (params) => createBuilder(addPutItem(state)(params)),
+  addUpdate: (params) => createBuilder(addUpdateItem(state)(params)),
+  addDelete: (params) => createBuilder(addDeleteItem(state)(params)),
+  addConditionCheck: (params) => createBuilder(addConditionCheckItem(state)(params)),
+  withClientRequestToken: (token) => createBuilder(setClientRequestToken(state)(token)),
   dbParams: () => toDbParams(state),
   execute: () => execute(state),
 });

package/src/builders/transact-write/types.ts

@@ -1,8 +1,46 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import type {
+  TransactWriteCommandInput,
+  TransactWriteCommandOutput,
+  PutCommandInput,
+  UpdateCommandInput,
+  DeleteCommandInput,
+} from '@aws-sdk/lib-dynamodb';
+
+// Extract types from AWS SDK's TransactWriteCommandInput
+type TransactWriteItems = NonNullable<TransactWriteCommandInput['TransactItems']>;
+type StrictTransactPut = NonNullable<TransactWriteItems[number]['Put']>;
+type StrictTransactUpdate = NonNullable<TransactWriteItems[number]['Update']>;
+type StrictTransactDelete = NonNullable<TransactWriteItems[number]['Delete']>;
+type StrictTransactConditionCheck = NonNullable<TransactWriteItems[number]['ConditionCheck']>;
+
+/**
+ * Parameters for a Put operation within a transaction
+ * Accepts both regular PutCommandInput and strict transaction Put params
+ */
+export type TransactPutParams = PutCommandInput | StrictTransactPut;
+
+/**
+ * Parameters for an Update operation within a transaction
+ * Accepts both regular UpdateCommandInput and strict transaction Update params
+ */
+export type TransactUpdateParams = UpdateCommandInput | StrictTransactUpdate;
+
+/**
+ * Parameters for a Delete operation within a transaction
+ * Accepts both regular DeleteCommandInput and strict transaction Delete params
+ */
+export type TransactDeleteParams = DeleteCommandInput | StrictTransactDelete;
+
+/**
+ * Parameters for a ConditionCheck operation within a transaction
+ */
+export type TransactConditionCheckParams = StrictTransactConditionCheck;
 
 /**
  * Represents a single item in a TransactWrite operation
+ * Using any internally to allow flexibility between CommandInput and strict transaction types
  */
 export type TransactWriteItem =
   | { Put: any }
@@ -23,11 +61,11 @@ export type TransactWriteState = {
  * TransactWrite builder interface
  */
 export type TransactWriteBuilder = {
-  readonly addPut: (params: any) => TransactWriteBuilder;
-  readonly addUpdate: (params: any) => TransactWriteBuilder;
-  readonly addDelete: (params: any) => TransactWriteBuilder;
-  readonly addConditionCheck: (params: any) => TransactWriteBuilder;
+  readonly addPut: (params: TransactPutParams) => TransactWriteBuilder;
+  readonly addUpdate: (params: TransactUpdateParams) => TransactWriteBuilder;
+  readonly addDelete: (params: TransactDeleteParams) => TransactWriteBuilder;
+  readonly addConditionCheck: (params: TransactConditionCheckParams) => TransactWriteBuilder;
   readonly withClientRequestToken: (token: string) => TransactWriteBuilder;
-  readonly dbParams: () => any;
-  readonly execute: () => Promise<any>;
+  readonly dbParams: () => TransactWriteCommandInput;
+  readonly execute: () => Promise<TransactWriteCommandOutput>;
 };

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

@@ -52,6 +52,49 @@ describe('UpdateBuilder', () => {
         ':score_2': 100,
       });
     });
+
+    test('should build params with multiple SET operations using object', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createUpdateBuilder<TestModel>(tableName, key, client)
+        .set({
+          name: 'John Doe',
+          age: 30,
+          score: 100,
+        })
+        .dbParams();
+
+      expect(params.UpdateExpression).toBe('SET #name = :name_0, #age = :age_1, #score = :score_2');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#age': 'age',
+        '#score': 'score',
+      });
+      expect(params.ExpressionAttributeValues).toEqual({
+        ':name_0': 'John Doe',
+        ':age_1': 30,
+        ':score_2': 100,
+      });
+    });
+
+    test('should combine single and multiple SET operations', () => {
+      const key: Partial<TestModel> = { pk: 'USER#1', sk: 'USER#1' };
+      const params = createUpdateBuilder<TestModel>(tableName, key, client)
+        .set('name', 'John Doe')
+        .set({ age: 30, score: 100 })
+        .dbParams();
+
+      expect(params.UpdateExpression).toBe('SET #name = :name_0, #age = :age_1, #score = :score_2');
+      expect(params.ExpressionAttributeNames).toEqual({
+        '#name': 'name',
+        '#age': 'age',
+        '#score': 'score',
+      });
+      expect(params.ExpressionAttributeValues).toEqual({
+        ':name_0': 'John Doe',
+        ':age_1': 30,
+        ':score_2': 100,
+      });
+    });
   });
 
   describe('REMOVE operations', () => {

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

@@ -59,8 +59,49 @@ export function createUpdateBuilder<Model>(
       );
     },
 
-    set(attr, value) {
-      const attrName = normalizeAttr(attr);
+    set(attrOrUpdates: keyof Model | AttrRef | Partial<Model>, value?: any) {
+      // Check if this is a multiple updates object
+      // An AttrRef has only 'name' property and is a string value
+      // Multiple updates is an object with no value parameter
+      if (
+        value === undefined &&
+        typeof attrOrUpdates === 'object' &&
+        attrOrUpdates !== null &&
+        !(
+          Object.keys(attrOrUpdates).length === 1 &&
+          'name' in attrOrUpdates &&
+          typeof (attrOrUpdates as any).name === 'string'
+        )
+      ) {
+        // Multiple updates case
+        const updates = attrOrUpdates as Partial<Model>;
+        const newActions: UpdateAction[] = [];
+
+        for (const [attr, val] of Object.entries(updates)) {
+          const attrName = attr;
+          const valueName = getUniqueValueName(attrName);
+          newActions.push({
+            expression: `#${attrName} = :${valueName}`,
+            names: { [`#${attrName}`]: attrName },
+            values: { [`:${valueName}`]: val },
+          });
+        }
+
+        return createUpdateBuilder(
+          tableName,
+          key,
+          client,
+          conditions,
+          { ...updateActions, set: [...updateActions.set, ...newActions] },
+          returnMode,
+          valueCounter,
+          enableTimestamps,
+          logger
+        );
+      }
+
+      // Single update case
+      const attrName = normalizeAttr(attrOrUpdates as keyof Model | AttrRef);
       const valueName = getUniqueValueName(attrName);
       const action: UpdateAction = {
         expression: `#${attrName} = :${valueName}`,
@@ -267,16 +308,13 @@ export function createUpdateBuilder<Model>(
       const response = await client.send(new UpdateCommand(params));
       logger?.log('UpdateCommand', params, response);
 
-      // Return the updated item based on returnMode
-      if (returnMode === 'ALL_NEW' && response.Attributes) {
-        return response.Attributes as Model;
-      }
-      if (returnMode === 'UPDATED_NEW' && response.Attributes) {
+      // Return the item based on returnMode
+      if (response.Attributes) {
         return response.Attributes as Model;
       }
 
-      // For other modes, return the key as a fallback
-      return key as Model;
+      // If no attributes returned (NONE mode), return undefined
+      return undefined as unknown as Model;
     },
   });