@ftschopp/dynatable-core 1.0.0 → 1.2.0

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;
     },
   });
 

package/src/builders/update/types.ts

@@ -1,3 +1,4 @@
+import type { UpdateCommandInput } from '@aws-sdk/lib-dynamodb';
 import { OperationBuilder, AttrRef } from '../shared';
 
 /**
@@ -12,11 +13,12 @@ export type UpdateAction = {
 /**
  * Builder interface for DynamoDB UpdateItem operations
  */
-export interface UpdateBuilder<Model> extends OperationBuilder<Model> {
+export interface UpdateBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbParams'> {
   /**
-   * Sets an attribute to a specific value
+   * Sets an attribute to a specific value, or sets multiple attributes at once
    */
   set(attr: keyof Model | AttrRef, value: any): UpdateBuilder<Model>;
+  set(updates: Partial<Model>): UpdateBuilder<Model>;
 
   /**
    * Removes an attribute from the item
@@ -39,4 +41,9 @@ export interface UpdateBuilder<Model> extends OperationBuilder<Model> {
   returning(
     mode: 'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW'
   ): UpdateBuilder<Model>;
+
+  /**
+   * Converts the builder state to DynamoDB UpdateItem parameters
+   */
+  dbParams(): UpdateCommandInput;
 }

package/src/core/types.test.ts

@@ -504,3 +504,140 @@ describe('Timestamp Type Inference', () => {
     expect(timestamps.updatedAt).toBe('2024-01-01T00:00:00.000Z');
   });
 });
+
+// ============================================================================
+// Nested Object & Array Type Inference Tests
+// ============================================================================
+
+describe('Nested Object and Array Type Inference', () => {
+  const TransactionSchema = {
+    format: 'dynatable:1.0.0',
+    version: '1.0.0',
+    indexes: { primary: { hash: 'PK', sort: 'SK' } },
+    models: {
+      Transaction: {
+        key: {
+          PK: { type: String, value: 'USER#${userId}' },
+          SK: { type: String, value: 'TX#${txId}' },
+        },
+        attributes: {
+          userId: { type: String, required: true },
+          txId: { type: String, required: true },
+          status: { type: String, required: true },
+          // Nested object with schema
+          address: {
+            type: Object,
+            schema: {
+              street: { type: String },
+              city: { type: String, required: true },
+              country: { type: String, required: true },
+            },
+          },
+          // Array of scalar items
+          tags: {
+            type: Array,
+            items: { type: String },
+            default: [],
+          },
+          // Array of objects with schema (like history in the real example)
+          history: {
+            type: Array,
+            default: [],
+            items: {
+              type: Object,
+              schema: {
+                date: { type: String },
+                description: { type: String },
+                status: { type: String, required: true },
+              },
+            },
+          },
+          // Deeply nested object
+          amount: {
+            type: Object,
+            schema: {
+              value: { type: Number, required: true },
+              currency: { type: String, required: true },
+              breakdown: {
+                type: Object,
+                schema: {
+                  base: { type: Number, required: true },
+                  fees: { type: Number, required: true },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  } as const satisfies SchemaDefinition;
+
+  type Transaction = InferModelFromSchema<typeof TransactionSchema, 'Transaction'>;
+
+  test('schema with nested Object attribute compiles', () => {
+    expect(TransactionSchema.models.Transaction.attributes.address.type).toBe(Object);
+  });
+
+  test('schema with Array of objects compiles', () => {
+    expect(TransactionSchema.models.Transaction.attributes.history.type).toBe(Array);
+  });
+
+  test('inferred type accepts valid nested object', () => {
+    const tx: Transaction = {
+      userId: 'u1',
+      txId: 'tx1',
+      status: 'PENDING',
+      address: { city: 'Buenos Aires', country: 'AR' },
+      tags: ['fast', 'verified'],
+      history: [
+        { date: '2024-01-01', description: 'Created', status: 'PENDING' },
+        { status: 'COMPLETED' },
+      ],
+      amount: {
+        value: 100,
+        currency: 'USD',
+        breakdown: { base: 90, fees: 10 },
+      },
+    };
+
+    expect(tx.userId).toBe('u1');
+    expect(tx.address?.city).toBe('Buenos Aires');
+    expect(tx.history?.[0]?.status).toBe('PENDING');
+    expect(tx.amount?.breakdown?.base).toBe(90);
+    expect(tx.tags?.[0]).toBe('fast');
+  });
+
+  test('inferred nested object type requires its required fields', () => {
+    type Address = NonNullable<Transaction['address']>;
+
+    // city and country are required — this must compile
+    const validAddress: Address = { city: 'BA', country: 'AR' };
+    expect(validAddress.city).toBe('BA');
+
+    // Verify the shape: optional `street`, required `city` and `country`
+    type AddressKeys = keyof Required<Address>;
+    const _keys: AddressKeys[] = ['street', 'city', 'country'];
+    expect(_keys).toContain('city');
+  });
+
+  test('model with nested attributes satisfies ModelDefinition', () => {
+    const model = {
+      key: {
+        PK: { type: String, value: 'ITEM#${id}' },
+        SK: { type: String, value: 'ITEM#${id}' },
+      },
+      attributes: {
+        id: { type: String, required: true },
+        meta: {
+          type: Object,
+          schema: {
+            createdBy: { type: String },
+            tags: { type: Array, items: { type: String } },
+          },
+        },
+      },
+    } as const satisfies ModelDefinition;
+
+    expect(model.attributes.meta.type).toBe(Object);
+  });
+});