betterddb 0.4.0 → 0.4.1

package/lib/betterddb.d.ts

@@ -1,4 +1,4 @@
-import { ZodSchema } from 'zod';
+import { z } from 'zod';
 import { DynamoDB } from 'aws-sdk';
 import { QueryBuilder } from './builders/query-builder';
 import { ScanBuilder } from './builders/scan-builder';
@@ -6,124 +6,59 @@ import { UpdateBuilder } from './builders/update-builder';
 import { CreateBuilder } from './builders/create-builder';
 import { GetBuilder } from './builders/get-builder';
 import { DeleteBuilder } from './builders/delete-builder';
+export type SchemaType<S extends z.ZodType<any>> = z.infer<S>;
 export type PrimaryKeyValue = string | number;
-/**
- * A key definition can be either a simple key (a property name)
- * or an object containing a build function that computes the value.
- * (In this design, the attribute name is provided separately.)
- */
-export type KeyDefinition<T> = keyof T | {
-    build: (rawKey: Partial<T>) => string;
+export type KeyDefinition<S extends z.ZodType<any>> = keyof SchemaType<S> | {
+    build: (rawKey: Partial<SchemaType<S>>) => string;
 };
-/**
- * Configuration for a primary (partition) key.
- */
-export interface PrimaryKeyConfig<T> {
-    /** The attribute name for the primary key in DynamoDB */
+export interface PrimaryKeyConfig<S extends z.ZodType<any>> {
     name: string;
-    /** How to compute the key value; if a keyof T, then the raw value is used;
-     * if an object, the build function is used.
-     */
-    definition: KeyDefinition<T>;
+    definition: KeyDefinition<S>;
 }
-/**
- * Configuration for a sort key.
- */
-export interface SortKeyConfig<T> {
-    /** The attribute name for the sort key in DynamoDB */
+export interface SortKeyConfig<S extends z.ZodType<any>> {
     name: string;
-    /** How to compute the sort key value */
-    definition: KeyDefinition<T>;
+    definition: KeyDefinition<S>;
 }
-/**
- * Configuration for a Global Secondary Index (GSI).
- */
-export interface GSIConfig<T> {
-    /** The name of the GSI in DynamoDB */
+export interface GSIConfig<S extends z.ZodType<any>> {
     name: string;
-    /** The primary key configuration for the GSI */
-    primary: PrimaryKeyConfig<T>;
-    /** The sort key configuration for the GSI, if any */
-    sort?: SortKeyConfig<T>;
+    primary: PrimaryKeyConfig<S>;
+    sort?: SortKeyConfig<S>;
 }
-/**
- * Keys configuration for the table.
- */
-export interface KeysConfig<T> {
-    primary: PrimaryKeyConfig<T>;
-    sort?: SortKeyConfig<T>;
+export interface KeysConfig<S extends z.ZodType<any>> {
+    primary: PrimaryKeyConfig<S>;
+    sort?: SortKeyConfig<S>;
     gsis?: {
-        [gsiName: string]: GSIConfig<T>;
+        [gsiName: string]: GSIConfig<S>;
     };
 }
-/**
- * Options for initializing BetterDDB.
- */
-export interface BetterDDBOptions<T> {
-    schema: ZodSchema<T>;
+export interface BetterDDBOptions<S extends z.ZodType<any>> {
+    schema: S;
     tableName: string;
     entityName: string;
-    keys: KeysConfig<T>;
+    keys: KeysConfig<S>;
     client: DynamoDB.DocumentClient;
-    /**
-     * If true, automatically inject timestamp fields:
-     * - On create, sets both `createdAt` and `updatedAt`
-     * - On update, sets `updatedAt`
-     *
-     * (T should include these fields if enabled.)
-     */
     autoTimestamps?: boolean;
 }
-/**
- * BetterDDB is a definition-based DynamoDB wrapper library.
- */
-export declare class BetterDDB<T> {
-    protected schema: ZodSchema<T>;
+export declare class BetterDDB<S extends z.ZodType<any>> {
+    protected schema: S;
     protected tableName: string;
     protected entityName: string;
     protected client: DynamoDB.DocumentClient;
-    protected keys: KeysConfig<T>;
+    protected keys: KeysConfig<S>;
     protected autoTimestamps: boolean;
-    constructor(options: BetterDDBOptions<T>);
-    getKeys(): KeysConfig<T>;
+    constructor(options: BetterDDBOptions<S>);
+    getKeys(): KeysConfig<S>;
     getTableName(): string;
     getClient(): DynamoDB.DocumentClient;
-    getSchema(): ZodSchema<T>;
+    getSchema(): S;
     getAutoTimestamps(): boolean;
-    protected getKeyValue(def: KeyDefinition<T>, rawKey: Partial<T>): string;
-    /**
-     * Build the primary key from a raw key object.
-     */
-    buildKey(rawKey: Partial<T>): Record<string, any>;
-    /**
-     * Build index attributes for each defined GSI.
-     */
-    buildIndexes(rawItem: Partial<T>): Record<string, any>;
-    /**
-     * Create an item:
-     * - Computes primary key and index attributes,
-     * - Optionally injects timestamps,
-     * - Validates the item and writes it to DynamoDB.
-     */
-    create(item: T): CreateBuilder<T>;
-    /**
-     * Get an item by its primary key.
-     */
-    get(rawKey: Partial<T>): GetBuilder<T>;
-    /**
-     * Update an item.
-     */
-    update(key: Partial<T>, expectedVersion?: number): UpdateBuilder<T>;
-    /**
-     * Delete an item.
-     */
-    delete(rawKey: Partial<T>): DeleteBuilder<T>;
-    /**
-     * Query items.
-     */
-    query(key: Partial<T>): QueryBuilder<T>;
-    /**
-     * Scan for items.
-     */
-    scan(): ScanBuilder<T>;
+    protected getKeyValue(def: KeyDefinition<S>, rawKey: Partial<SchemaType<S>>): string;
+    buildKey(rawKey: Partial<SchemaType<S>>): Record<string, any>;
+    buildIndexes(rawItem: Partial<SchemaType<S>>): Record<string, any>;
+    create(item: SchemaType<S>): CreateBuilder<SchemaType<S>>;
+    get(rawKey: Partial<SchemaType<S>>): GetBuilder<SchemaType<S>>;
+    update(key: Partial<SchemaType<S>>, expectedVersion?: number): UpdateBuilder<SchemaType<S>>;
+    delete(rawKey: Partial<SchemaType<S>>): DeleteBuilder<SchemaType<S>>;
+    query(key: Partial<SchemaType<S>>): QueryBuilder<SchemaType<S>>;
+    scan(): ScanBuilder<SchemaType<S>>;
 }

package/lib/betterddb.js

@@ -7,18 +7,15 @@ const update_builder_1 = require("./builders/update-builder");
 const create_builder_1 = require("./builders/create-builder");
 const get_builder_1 = require("./builders/get-builder");
 const delete_builder_1 = require("./builders/delete-builder");
-/**
- * BetterDDB is a definition-based DynamoDB wrapper library.
- */
 class BetterDDB {
     constructor(options) {
         var _a;
         this.schema = options.schema;
         this.tableName = options.tableName;
         this.entityName = options.entityName.toUpperCase();
-        this.keys = options.keys;
         this.client = options.client;
         this.autoTimestamps = (_a = options.autoTimestamps) !== null && _a !== void 0 ? _a : false;
+        this.keys = options.keys;
     }
     getKeys() {
         return this.keys;
@@ -35,106 +32,49 @@ class BetterDDB {
     getAutoTimestamps() {
         return this.autoTimestamps;
     }
-    // Helper: Retrieve the key value from a KeyDefinition.
     getKeyValue(def, rawKey) {
         if (typeof def === 'string' || typeof def === 'number' || typeof def === 'symbol') {
             return String(rawKey[def]);
         }
-        else {
-            return def.build(rawKey);
-        }
+        return def.build(rawKey);
     }
-    /**
-     * Build the primary key from a raw key object.
-     */
     buildKey(rawKey) {
         const keyObj = {};
-        // For primary (partition) key:
-        const pkConfig = this.keys.primary;
-        keyObj[pkConfig.name] =
-            (typeof pkConfig.definition === 'string' ||
-                typeof pkConfig.definition === 'number' ||
-                typeof pkConfig.definition === 'symbol')
-                ? String(rawKey[pkConfig.definition])
-                : pkConfig.definition.build(rawKey);
-        // For sort key, if defined:
-        if (this.keys.sort) {
-            const skConfig = this.keys.sort;
-            keyObj[skConfig.name] =
-                (typeof skConfig.definition === 'string' ||
-                    typeof skConfig.definition === 'number' ||
-                    typeof skConfig.definition === 'symbol')
-                    ? String(rawKey[skConfig.definition])
-                    : skConfig.definition.build(rawKey);
+        const { primary, sort } = this.keys;
+        keyObj[primary.name] = this.getKeyValue(primary.definition, rawKey);
+        if (sort) {
+            keyObj[sort.name] = this.getKeyValue(sort.definition, rawKey);
         }
         return keyObj;
     }
-    /**
-     * Build index attributes for each defined GSI.
-     */
     buildIndexes(rawItem) {
         const indexAttributes = {};
         if (this.keys.gsis) {
-            for (const gsiName in this.keys.gsis) {
-                const gsiConfig = this.keys.gsis[gsiName];
-                // Compute primary index attribute.
-                const primaryConfig = gsiConfig.primary;
-                indexAttributes[primaryConfig.name] =
-                    (typeof primaryConfig.definition === 'string' ||
-                        typeof primaryConfig.definition === 'number' ||
-                        typeof primaryConfig.definition === 'symbol')
-                        ? String(rawItem[primaryConfig.definition])
-                        : primaryConfig.definition.build(rawItem);
-                // Compute sort index attribute if provided.
-                if (gsiConfig.sort) {
-                    const sortConfig = gsiConfig.sort;
-                    indexAttributes[sortConfig.name] =
-                        (typeof sortConfig.definition === 'string' ||
-                            typeof sortConfig.definition === 'number' ||
-                            typeof sortConfig.definition === 'symbol')
-                            ? String(rawItem[sortConfig.definition])
-                            : sortConfig.definition.build(rawItem);
+            Object.entries(this.keys.gsis).forEach(([_, gsiConfig]) => {
+                const { primary, sort } = gsiConfig;
+                indexAttributes[primary.name] = this.getKeyValue(primary.definition, rawItem);
+                if (sort) {
+                    indexAttributes[sort.name] = this.getKeyValue(sort.definition, rawItem);
                 }
-            }
+            });
         }
         return indexAttributes;
     }
-    /**
-     * Create an item:
-     * - Computes primary key and index attributes,
-     * - Optionally injects timestamps,
-     * - Validates the item and writes it to DynamoDB.
-     */
     create(item) {
         return new create_builder_1.CreateBuilder(this, item);
     }
-    /**
-     * Get an item by its primary key.
-     */
     get(rawKey) {
         return new get_builder_1.GetBuilder(this, rawKey);
     }
-    /**
-     * Update an item.
-     */
     update(key, expectedVersion) {
         return new update_builder_1.UpdateBuilder(this, key, expectedVersion);
     }
-    /**
-     * Delete an item.
-     */
     delete(rawKey) {
         return new delete_builder_1.DeleteBuilder(this, rawKey);
     }
-    /**
-     * Query items.
-     */
     query(key) {
         return new query_builder_1.QueryBuilder(this, key);
     }
-    /**
-     * Scan for items.
-     */
     scan() {
         return new scan_builder_1.ScanBuilder(this);
     }

package/lib/builders/create-builder.d.ts

@@ -1,14 +1,15 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
-export declare class CreateBuilder<T> {
+import { z } from 'zod';
+export declare class CreateBuilder<S extends z.ZodType<any>> {
     private parent;
     private item;
     private extraTransactItems;
-    constructor(parent: BetterDDB<T>, item: T);
-    execute(): Promise<T>;
+    constructor(parent: BetterDDB<S>, item: S);
+    execute(): Promise<S>;
     transactWrite(ops: DynamoDB.DocumentClient.TransactWriteItemList | DynamoDB.DocumentClient.TransactWriteItem): this;
     toTransactPut(): DynamoDB.DocumentClient.TransactWriteItem;
-    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
-    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
-    finally(onfinally?: (() => void) | null): Promise<T>;
+    then<TResult1 = S, TResult2 = never>(onfulfilled?: ((value: S) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<S | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<S>;
 }

package/lib/builders/delete-builder.d.ts

@@ -1,11 +1,12 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
-export declare class DeleteBuilder<T> {
+import { z } from 'zod';
+export declare class DeleteBuilder<S extends z.ZodType<any>> {
     private parent;
     private key;
     private condition?;
     private extraTransactItems;
-    constructor(parent: BetterDDB<T>, key: Partial<T>);
+    constructor(parent: BetterDDB<S>, key: Partial<S>);
     /**
      * Specify a condition expression for the delete operation.
      */

package/lib/builders/get-builder.d.ts

@@ -1,20 +1,21 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
-export declare class GetBuilder<T> {
+import { z } from 'zod';
+export declare class GetBuilder<S extends z.ZodType<any>> {
     private parent;
     private key;
     private projectionExpression?;
     private expressionAttributeNames;
     private extraTransactItems;
-    constructor(parent: BetterDDB<T>, key: Partial<T>);
+    constructor(parent: BetterDDB<S>, key: Partial<S>);
     /**
      * Specify a projection by providing an array of attribute names.
      */
-    withProjection(attributes: (keyof T)[]): this;
-    execute(): Promise<T | null>;
+    withProjection(attributes: (keyof S)[]): this;
+    execute(): Promise<S | null>;
     transactGet(ops: DynamoDB.DocumentClient.TransactGetItemList | DynamoDB.DocumentClient.TransactGetItem): this;
     toTransactGet(): DynamoDB.DocumentClient.TransactGetItem;
-    then<TResult1 = T | null, TResult2 = never>(onfulfilled?: ((value: T | null) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
-    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T | null | TResult>;
-    finally(onfinally?: (() => void) | null): Promise<T | null>;
+    then<TResult1 = S | null, TResult2 = never>(onfulfilled?: ((value: S | null) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<S | null | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<S | null>;
 }

package/lib/builders/query-builder.d.ts

@@ -1,5 +1,6 @@
 import { BetterDDB } from '../betterddb';
-export declare class QueryBuilder<T> {
+import { z } from 'zod';
+export declare class QueryBuilder<S extends z.ZodType<any>> {
     private parent;
     private key;
     private filters;
@@ -10,18 +11,18 @@ export declare class QueryBuilder<T> {
     private limit?;
     private lastKey?;
     private ascending;
-    constructor(parent: BetterDDB<T>, key: Partial<T>);
+    constructor(parent: BetterDDB<S>, key: Partial<S>);
     usingIndex(indexName: string): this;
     sortAscending(): this;
     sortDescending(): this;
-    where(attribute: keyof T, operator: 'eq' | 'begins_with' | 'between', values: any | [any, any]): this;
+    where(attribute: keyof S, operator: 'eq' | 'begins_with' | 'between', values: any | [any, any]): this;
     limitResults(limit: number): this;
     startFrom(lastKey: Record<string, any>): this;
     /**
      * Executes the query and returns a Promise that resolves with an array of items.
      */
-    execute(): Promise<T[]>;
-    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
-    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T[] | TResult>;
-    finally(onfinally?: (() => void) | null): Promise<T[]>;
+    execute(): Promise<S[]>;
+    then<TResult1 = S[], TResult2 = never>(onfulfilled?: ((value: S[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<S[] | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<S[]>;
 }

package/lib/builders/scan-builder.d.ts

@@ -1,20 +1,21 @@
 import { BetterDDB } from '../betterddb';
-export declare class ScanBuilder<T> {
+import { z } from 'zod';
+export declare class ScanBuilder<S extends z.ZodType<any>> {
     private parent;
     private filters;
     private expressionAttributeNames;
     private expressionAttributeValues;
     private limit?;
     private lastKey?;
-    constructor(parent: BetterDDB<T>);
-    where(attribute: keyof T, operator: 'eq' | 'begins_with' | 'between', values: any | [any, any]): this;
+    constructor(parent: BetterDDB<S>);
+    where(attribute: keyof S, operator: 'eq' | 'begins_with' | 'between', values: any | [any, any]): this;
     limitResults(limit: number): this;
     startFrom(lastKey: Record<string, any>): this;
     /**
      * Executes the scan and returns a Promise that resolves with an array of items.
      */
-    execute(): Promise<T[]>;
-    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
-    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T[] | TResult>;
-    finally(onfinally?: (() => void) | null): Promise<T[]>;
+    execute(): Promise<S[]>;
+    then<TResult1 = S[], TResult2 = never>(onfulfilled?: ((value: S[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<S[] | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<S[]>;
 }

package/lib/builders/update-builder.d.ts

@@ -1,17 +1,18 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
-export declare class UpdateBuilder<T> {
+import { z } from 'zod';
+export declare class UpdateBuilder<S extends z.ZodType<any>> {
     private parent;
     private key;
     private actions;
     private condition?;
     private expectedVersion?;
     private extraTransactItems;
-    constructor(parent: BetterDDB<T>, key: Partial<T>, expectedVersion?: number);
-    set(attrs: Partial<T>): this;
-    remove(attrs: (keyof T)[]): this;
-    add(attrs: Partial<Record<keyof T, number | Set<any>>>): this;
-    delete(attrs: Partial<Record<keyof T, Set<any>>>): this;
+    constructor(parent: BetterDDB<S>, key: Partial<S>, expectedVersion?: number);
+    set(attrs: Partial<S>): this;
+    remove(attrs: (keyof S)[]): this;
+    add(attrs: Partial<Record<keyof S, number | Set<any>>>): this;
+    delete(attrs: Partial<Record<keyof S, Set<any>>>): this;
     /**
      * Adds a condition expression to the update.
      */
@@ -31,5 +32,5 @@ export declare class UpdateBuilder<T> {
     /**
      * Commits the update immediately by calling the parent's update method.
      */
-    execute(): Promise<T>;
+    execute(): Promise<S>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "betterddb",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "A definition-based DynamoDB wrapper library that provides a schema-driven and fully typesafe DAL.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/betterddb.ts

@@ -1,4 +1,4 @@
-import { ZodSchema } from 'zod';
+import { z } from 'zod';
 import { DynamoDB } from 'aws-sdk';
 import { QueryBuilder } from './builders/query-builder';
 import { ScanBuilder } from './builders/scan-builder';
@@ -7,117 +7,79 @@ import { CreateBuilder } from './builders/create-builder';
 import { GetBuilder } from './builders/get-builder';
 import { DeleteBuilder } from './builders/delete-builder';
 
+export type SchemaType<S extends z.ZodType<any>> = z.infer<S>;
+
 export type PrimaryKeyValue = string | number;
 
-/**
- * A key definition can be either a simple key (a property name)
- * or an object containing a build function that computes the value.
- * (In this design, the attribute name is provided separately.)
- */
-export type KeyDefinition<T> =
-  | keyof T
+export type KeyDefinition<S extends z.ZodType<any>> =
+  | keyof SchemaType<S>
   | {
-      build: (rawKey: Partial<T>) => string;
+      build: (rawKey: Partial<SchemaType<S>>) => string;
     };
 
-/**
- * Configuration for a primary (partition) key.
- */
-export interface PrimaryKeyConfig<T> {
-  /** The attribute name for the primary key in DynamoDB */
+export interface PrimaryKeyConfig<S extends z.ZodType<any>> {
   name: string;
-  /** How to compute the key value; if a keyof T, then the raw value is used;
-   * if an object, the build function is used.
-   */
-  definition: KeyDefinition<T>;
+  definition: KeyDefinition<S>;
 }
 
-/**
- * Configuration for a sort key.
- */
-export interface SortKeyConfig<T> {
-  /** The attribute name for the sort key in DynamoDB */
+export interface SortKeyConfig<S extends z.ZodType<any>> {
   name: string;
-  /** How to compute the sort key value */
-  definition: KeyDefinition<T>;
+  definition: KeyDefinition<S>;
 }
 
-/**
- * Configuration for a Global Secondary Index (GSI).
- */
-export interface GSIConfig<T> {
-  /** The name of the GSI in DynamoDB */
+export interface GSIConfig<S extends z.ZodType<any>> {
   name: string;
-  /** The primary key configuration for the GSI */
-  primary: PrimaryKeyConfig<T>;
-  /** The sort key configuration for the GSI, if any */
-  sort?: SortKeyConfig<T>;
+  primary: PrimaryKeyConfig<S>;
+  sort?: SortKeyConfig<S>;
 }
 
-/**
- * Keys configuration for the table.
- */
-export interface KeysConfig<T> {
-  primary: PrimaryKeyConfig<T>;
-  sort?: SortKeyConfig<T>;
+export interface KeysConfig<S extends z.ZodType<any>> {
+  primary: PrimaryKeyConfig<S>;
+  sort?: SortKeyConfig<S>;
   gsis?: {
-    [gsiName: string]: GSIConfig<T>;
+    [gsiName: string]: GSIConfig<S>;
   };
 }
 
-/**
- * Options for initializing BetterDDB.
- */
-export interface BetterDDBOptions<T> {
-  schema: ZodSchema<T>;
+export interface BetterDDBOptions<S extends z.ZodType<any>> {
+  schema: S;
   tableName: string;
   entityName: string;
-  keys: KeysConfig<T>;
+  keys: KeysConfig<S>;
   client: DynamoDB.DocumentClient;
-  /**
-   * If true, automatically inject timestamp fields:
-   * - On create, sets both `createdAt` and `updatedAt`
-   * - On update, sets `updatedAt`
-   *
-   * (T should include these fields if enabled.)
-   */
   autoTimestamps?: boolean;
 }
 
-/**
- * BetterDDB is a definition-based DynamoDB wrapper library.
- */
-export class BetterDDB<T> {
-  protected schema: ZodSchema<T>;
+export class BetterDDB<S extends z.ZodType<any>> {
+  protected schema: S;
   protected tableName: string;
   protected entityName: string;
   protected client: DynamoDB.DocumentClient;
-  protected keys: KeysConfig<T>;
+  protected keys: KeysConfig<S>;
   protected autoTimestamps: boolean;
 
-  constructor(options: BetterDDBOptions<T>) {
+  constructor(options: BetterDDBOptions<S>) {
     this.schema = options.schema;
     this.tableName = options.tableName;
     this.entityName = options.entityName.toUpperCase();
-    this.keys = options.keys;
     this.client = options.client;
     this.autoTimestamps = options.autoTimestamps ?? false;
+    this.keys = options.keys;
   }
 
-  public getKeys(): KeysConfig<T> {
+  public getKeys(): KeysConfig<S> {
     return this.keys;
   }
-  
+
   public getTableName(): string {
     return this.tableName;
   }
-  
+
   public getClient(): DynamoDB.DocumentClient {
     return this.client;
   }
-  
-  
-  public getSchema(): ZodSchema<T> {
+
+  public getSchema(): S {
     return this.schema;
   }
 
@@ -125,118 +87,70 @@ export class BetterDDB<T> {
     return this.autoTimestamps;
   }
 
-  // Helper: Retrieve the key value from a KeyDefinition.
-  protected getKeyValue(def: KeyDefinition<T>, rawKey: Partial<T>): string {
+  protected getKeyValue(
+    def: KeyDefinition<S>,
+    rawKey: Partial<SchemaType<S>>
+  ): string {
     if (typeof def === 'string' || typeof def === 'number' || typeof def === 'symbol') {
-      return String(rawKey[def]);
-    } else {
-      return def.build(rawKey);
+      return String(rawKey[def as keyof typeof rawKey]);
     }
+    return def.build(rawKey);
   }
 
-  /**
-   * Build the primary key from a raw key object.
-   */
-  public buildKey(rawKey: Partial<T>): Record<string, any> {
+  public buildKey(rawKey: Partial<SchemaType<S>>): Record<string, any> {
     const keyObj: Record<string, any> = {};
-  
-    // For primary (partition) key:
-    const pkConfig = this.keys.primary;
-    keyObj[pkConfig.name] =
-      (typeof pkConfig.definition === 'string' ||
-       typeof pkConfig.definition === 'number' ||
-       typeof pkConfig.definition === 'symbol')
-        ? String((rawKey as any)[pkConfig.definition])
-        : pkConfig.definition.build(rawKey);
-  
-    // For sort key, if defined:
-    if (this.keys.sort) {
-      const skConfig = this.keys.sort;
-      keyObj[skConfig.name] =
-        (typeof skConfig.definition === 'string' ||
-         typeof skConfig.definition === 'number' ||
-         typeof skConfig.definition === 'symbol')
-          ? String((rawKey as any)[skConfig.definition])
-          : skConfig.definition.build(rawKey);
+    const { primary, sort } = this.keys;
+
+    keyObj[primary.name] = this.getKeyValue(primary.definition, rawKey);
+
+    if (sort) {
+      keyObj[sort.name] = this.getKeyValue(sort.definition, rawKey);
     }
+
     return keyObj;
   }
-  
-  /**
-   * Build index attributes for each defined GSI.
-   */
-  public buildIndexes(rawItem: Partial<T>): Record<string, any> {
+
+  public buildIndexes(rawItem: Partial<SchemaType<S>>): Record<string, any> {
     const indexAttributes: Record<string, any> = {};
+    
     if (this.keys.gsis) {
-      for (const gsiName in this.keys.gsis) {
-        const gsiConfig = this.keys.gsis[gsiName];
-  
-        // Compute primary index attribute.
-        const primaryConfig = gsiConfig.primary;
-        indexAttributes[primaryConfig.name] =
-          (typeof primaryConfig.definition === 'string' ||
-           typeof primaryConfig.definition === 'number' ||
-           typeof primaryConfig.definition === 'symbol')
-            ? String((rawItem as any)[primaryConfig.definition])
-            : primaryConfig.definition.build(rawItem);
-  
-        // Compute sort index attribute if provided.
-        if (gsiConfig.sort) {
-          const sortConfig = gsiConfig.sort;
-          indexAttributes[sortConfig.name] =
-            (typeof sortConfig.definition === 'string' ||
-             typeof sortConfig.definition === 'number' ||
-             typeof sortConfig.definition === 'symbol')
-              ? String((rawItem as any)[sortConfig.definition])
-              : sortConfig.definition.build(rawItem);
+      Object.entries(this.keys.gsis).forEach(([_, gsiConfig]) => {
+        const { primary, sort } = gsiConfig;
+        indexAttributes[primary.name] = this.getKeyValue(primary.definition, rawItem);
+        
+        if (sort) {
+          indexAttributes[sort.name] = this.getKeyValue(sort.definition, rawItem);
         }
-      }
+      });
     }
+    
     return indexAttributes;
   }
-  
-  /**
-   * Create an item:
-   * - Computes primary key and index attributes,
-   * - Optionally injects timestamps,
-   * - Validates the item and writes it to DynamoDB.
-   */
-  public create(item: T): CreateBuilder<T> {
-    return new CreateBuilder<T>(this, item);
+
+  public create(item: SchemaType<S>): CreateBuilder<SchemaType<S>> {
+    return new CreateBuilder<SchemaType<S>>(this, item);
   }
-  
-  /**
-   * Get an item by its primary key.
-   */
-  public get(rawKey: Partial<T>): GetBuilder<T> {
-    return new GetBuilder<T>(this, rawKey);
+
+  public get(rawKey: Partial<SchemaType<S>>): GetBuilder<SchemaType<S>> {
+    return new GetBuilder<SchemaType<S>>(this, rawKey);
   }
 
-  /**
-   * Update an item.
-   */
-  public update(key: Partial<T>, expectedVersion?: number): UpdateBuilder<T> {
-    return new UpdateBuilder<T>(this, key, expectedVersion);
+  public update(
+    key: Partial<SchemaType<S>>,
+    expectedVersion?: number
+  ): UpdateBuilder<SchemaType<S>> {
+    return new UpdateBuilder<SchemaType<S>>(this, key, expectedVersion);
   }
 
-  /**
-   * Delete an item.
-   */
-  public delete(rawKey: Partial<T>): DeleteBuilder<T> {
-    return new DeleteBuilder<T>(this, rawKey);
+  public delete(rawKey: Partial<SchemaType<S>>): DeleteBuilder<SchemaType<S>> {
+    return new DeleteBuilder<SchemaType<S>>(this, rawKey);
   }
 
-  /**
-   * Query items.
-   */
-  public query(key: Partial<T>): QueryBuilder<T> {
-    return new QueryBuilder<T>(this, key);
+  public query(key: Partial<SchemaType<S>>): QueryBuilder<SchemaType<S>> {
+    return new QueryBuilder<SchemaType<S>>(this, key);
   }
 
-  /**
-   * Scan for items.
-   */ 
-  public scan(): ScanBuilder<T> {
-    return new ScanBuilder<T>(this);
+  public scan(): ScanBuilder<SchemaType<S>> {
+    return new ScanBuilder<SchemaType<S>>(this);
   }
-}
+}

package/src/builders/create-builder.ts

@@ -1,12 +1,13 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
+import { z } from 'zod';
 
-export class CreateBuilder<T> {
+export class CreateBuilder<S extends z.ZodType<any>> {
   private extraTransactItems: DynamoDB.DocumentClient.TransactWriteItemList = [];
 
-  constructor(private parent: BetterDDB<T>, private item: T) {}
+  constructor(private parent: BetterDDB<S>, private item: S) {}
 
-  public async execute(): Promise<T> {
+  public async execute(): Promise<S> {
     if (this.extraTransactItems.length > 0) {
       // Build our update transaction item.
       const myTransactItem = this.toTransactPut();
@@ -25,7 +26,7 @@ export class CreateBuilder<T> {
     let item = this.item;
     if (this.parent.getAutoTimestamps()) {
       const now = new Date().toISOString();
-      item = { ...item, createdAt: now, updatedAt: now } as T;
+      item = { ...item, createdAt: now, updatedAt: now } as S;
     }
     // Validate the item using the schema.
     const validated = this.parent.getSchema().parse(item);
@@ -65,18 +66,18 @@ export class CreateBuilder<T> {
     return { Put: putItem };
   }
 
-  public then<TResult1 = T, TResult2 = never>(
-    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+  public then<TResult1 = S, TResult2 = never>(
+    onfulfilled?: ((value: S) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
   ): Promise<TResult1 | TResult2> {
     return this.execute().then(onfulfilled, onrejected);
   }
   public catch<TResult = never>(
     onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
-  ): Promise<T | TResult> {
+  ): Promise<S | TResult> {
     return this.execute().catch(onrejected);
   }
-  public finally(onfinally?: (() => void) | null): Promise<T> {
+  public finally(onfinally?: (() => void) | null): Promise<S> {
     return this.execute().finally(onfinally);
   }
 }

package/src/builders/delete-builder.ts

@@ -1,10 +1,11 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
+import { z } from 'zod';
 
-export class DeleteBuilder<T> {
+export class DeleteBuilder<S extends z.ZodType<any>> {
   private condition?: { expression: string; attributeValues: Record<string, any> };
   private extraTransactItems: DynamoDB.DocumentClient.TransactWriteItemList = [];
-  constructor(private parent: BetterDDB<T>, private key: Partial<T>) {}
+  constructor(private parent: BetterDDB<S>, private key: Partial<S>) {}
 
   /**
    * Specify a condition expression for the delete operation.

package/src/builders/get-builder.ts

@@ -1,16 +1,17 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
+import { z } from 'zod';
 
-export class GetBuilder<T> {
+export class GetBuilder<S extends z.ZodType<any>> {
   private projectionExpression?: string;
   private expressionAttributeNames: Record<string, string> = {};
   private extraTransactItems: DynamoDB.DocumentClient.TransactGetItemList = [];
-  constructor(private parent: BetterDDB<T>, private key: Partial<T>) {}
+  constructor(private parent: BetterDDB<S>, private key: Partial<S>) {}
 
   /**
    * Specify a projection by providing an array of attribute names.
    */
-  public withProjection(attributes: (keyof T)[]): this {
+  public withProjection(attributes: (keyof S)[]): this {
     this.projectionExpression = attributes.map(attr => `#${String(attr)}`).join(', ');
     for (const attr of attributes) {
       this.expressionAttributeNames[`#${String(attr)}`] = String(attr);
@@ -18,7 +19,7 @@ export class GetBuilder<T> {
     return this;
   }
 
-  public async execute(): Promise<T | null> {
+  public async execute(): Promise<S | null> {
     if (this.extraTransactItems.length > 0) {
       // Build our update transaction item.
       const myTransactItem = this.toTransactGet();
@@ -66,18 +67,18 @@ export class GetBuilder<T> {
     return { Get: getItem };
   }
 
-  public then<TResult1 = T | null, TResult2 = never>(
-    onfulfilled?: ((value: T | null) => TResult1 | PromiseLike<TResult1>) | null,
+  public then<TResult1 = S | null, TResult2 = never>(
+    onfulfilled?: ((value: S | null) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
   ): Promise<TResult1 | TResult2> {
     return this.execute().then(onfulfilled, onrejected);
   }
   public catch<TResult = never>(
     onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
-  ): Promise<T | null | TResult> {
+  ): Promise<S | null | TResult> {
     return this.execute().catch(onrejected);
   }
-  public finally(onfinally?: (() => void) | null): Promise<T | null> {
+  public finally(onfinally?: (() => void) | null): Promise<S | null> {
     return this.execute().finally(onfinally);
   }
 }

package/src/builders/query-builder.ts

@@ -1,7 +1,8 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
+import { z } from 'zod';
 
-export class QueryBuilder<T> {
+export class QueryBuilder<S extends z.ZodType<any>> {
   private filters: string[] = [];
   private expressionAttributeNames: Record<string, string> = {};
   private expressionAttributeValues: Record<string, any> = {};
@@ -11,7 +12,7 @@ export class QueryBuilder<T> {
   private lastKey?: Record<string, any>;
   private ascending: boolean = true;
 
-  constructor(private parent: BetterDDB<T>, private key: Partial<T>) {}
+  constructor(private parent: BetterDDB<S>, private key: Partial<S>) {}
 
   public usingIndex(indexName: string): this {
     this.indexName = indexName;
@@ -29,7 +30,7 @@ export class QueryBuilder<T> {
   }
 
   public where(
-    attribute: keyof T,
+    attribute: keyof S,
     operator: 'eq' | 'begins_with' | 'between',
     values: any | [any, any]
   ): this {
@@ -73,7 +74,7 @@ export class QueryBuilder<T> {
   /**
    * Executes the query and returns a Promise that resolves with an array of items.
    */
-  public async execute(): Promise<T[]> {
+  public async execute(): Promise<S[]> {
     // Build a simple key condition for the partition key.
     const keys = this.parent.getKeys();
     const pkName = keys.primary.name;
@@ -110,18 +111,18 @@ export class QueryBuilder<T> {
   }
 
   // Thenable implementation.
-  public then<TResult1 = T[], TResult2 = never>(
-    onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
+  public then<TResult1 = S[], TResult2 = never>(
+    onfulfilled?: ((value: S[]) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
   ): Promise<TResult1 | TResult2> {
     return this.execute().then(onfulfilled, onrejected);
   }
   public catch<TResult = never>(
     onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
-  ): Promise<T[] | TResult> {
+  ): Promise<S[] | TResult> {
     return this.execute().catch(onrejected);
   }
-  public finally(onfinally?: (() => void) | null): Promise<T[]> {
+  public finally(onfinally?: (() => void) | null): Promise<S[]> {
     return this.execute().finally(onfinally);
   }
 }

package/src/builders/scan-builder.ts

@@ -1,17 +1,18 @@
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
+import { z } from 'zod';
 
-export class ScanBuilder<T> {
+export class ScanBuilder<S extends z.ZodType<any>> {
   private filters: string[] = [];
   private expressionAttributeNames: Record<string, string> = {};
   private expressionAttributeValues: Record<string, any> = {};
   private limit?: number;
   private lastKey?: Record<string, any>;
 
-  constructor(private parent: BetterDDB<T>) {}
+  constructor(private parent: BetterDDB<S>) {}
 
   public where(
-    attribute: keyof T,
+    attribute: keyof S,
     operator: 'eq' | 'begins_with' | 'between',
     values: any | [any, any]
   ): this {
@@ -55,7 +56,7 @@ export class ScanBuilder<T> {
   /**
    * Executes the scan and returns a Promise that resolves with an array of items.
    */
-  public async execute(): Promise<T[]> {
+  public async execute(): Promise<S[]> {
     const params: DynamoDB.DocumentClient.ScanInput = {
       TableName: this.parent.getTableName(),
       ExpressionAttributeNames: this.expressionAttributeNames,
@@ -73,18 +74,18 @@ export class ScanBuilder<T> {
   }
 
   // Thenable implementation.
-  public then<TResult1 = T[], TResult2 = never>(
-    onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
+  public then<TResult1 = S[], TResult2 = never>(
+    onfulfilled?: ((value: S[]) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
   ): Promise<TResult1 | TResult2> {
     return this.execute().then(onfulfilled, onrejected);
   }
   public catch<TResult = never>(
     onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
-  ): Promise<T[] | TResult> {
+  ): Promise<S[] | TResult> {
     return this.execute().catch(onrejected);
   }
-  public finally(onfinally?: (() => void) | null): Promise<T[]> {
+  public finally(onfinally?: (() => void) | null): Promise<S[]> {
     return this.execute().finally(onfinally);
   }
 }

package/src/builders/update-builder.ts

@@ -1,43 +1,44 @@
 
 import { DynamoDB } from 'aws-sdk';
 import { BetterDDB } from '../betterddb';
+import { z } from 'zod';
 
-interface UpdateActions<T> {
-  set?: Partial<T>;
-  remove?: (keyof T)[];
-  add?: Partial<Record<keyof T, number | Set<any>>>;
-  delete?: Partial<Record<keyof T, Set<any>>>;
+interface UpdateActions<S extends z.ZodType<any>> {
+  set?: Partial<S>;
+  remove?: (keyof S)[];
+  add?: Partial<Record<keyof S, number | Set<any>>>;
+  delete?: Partial<Record<keyof S, Set<any>>>;
 }
 
-export class UpdateBuilder<T> {
-  private actions: UpdateActions<T> = {};
+export class UpdateBuilder<S extends z.ZodType<any>> {
+  private actions: UpdateActions<S> = {};
   private condition?: { expression: string; attributeValues: Record<string, any> };
   private expectedVersion?: number;
   // When using transaction mode, we store extra transaction items.
   private extraTransactItems: DynamoDB.DocumentClient.TransactWriteItemList = [];
 
   // Reference to the parent BetterDDB instance and key.
-  constructor(private parent: BetterDDB<T>, private key: Partial<T>, expectedVersion?: number) {
+  constructor(private parent: BetterDDB<S>, private key: Partial<S>, expectedVersion?: number) {
     this.expectedVersion = expectedVersion;
   }
 
   // Chainable methods:
-  public set(attrs: Partial<T>): this {
+  public set(attrs: Partial<S>): this {
     this.actions.set = { ...this.actions.set, ...attrs };
     return this;
   }
 
-  public remove(attrs: (keyof T)[]): this {
+  public remove(attrs: (keyof S)[]): this {
     this.actions.remove = [...(this.actions.remove || []), ...attrs];
     return this;
   }
 
-  public add(attrs: Partial<Record<keyof T, number | Set<any>>>): this {
+  public add(attrs: Partial<Record<keyof S, number | Set<any>>>): this {
     this.actions.add = { ...this.actions.add, ...attrs };
     return this;
   }
 
-  public delete(attrs: Partial<Record<keyof T, Set<any>>>): this {
+  public delete(attrs: Partial<Record<keyof S, Set<any>>>): this {
     this.actions.delete = { ...this.actions.delete, ...attrs };
     return this;
   }
@@ -191,7 +192,7 @@ export class UpdateBuilder<T> {
   /**
    * Commits the update immediately by calling the parent's update method.
    */
-  public async execute(): Promise<T> {
+  public async execute(): Promise<S> {
     if (this.extraTransactItems.length > 0) {
       // Build our update transaction item.
       const myTransactItem = this.toTransactUpdate();

package/test/create.test.ts

@@ -24,15 +24,16 @@ const UserSchema = z.object({
   email: z.string().email(),
   createdAt: z.string(),
   updatedAt: z.string(),
-}).passthrough();
+});
 
 const userDdb = new BetterDDB({
   schema: UserSchema,
   tableName: TEST_TABLE,
   entityName: ENTITY_NAME,
   keys: {
-    primary: { name: PRIMARY_KEY, definition: { build: (raw) => raw.id! } },
-    sort: { name: SORT_KEY, definition: { build: (raw) => raw.email! } },
+    primary: { name: "pk", definition: { build: (raw) => `USER#${raw.id}` } },
+    sort: { name: "sk", definition: { build: (raw) => `EMAIL#${raw.email}` } },
+    gsis: { gsi1: { name: 'gsi1', primary: { name: "gsi1pk", definition: { build: (raw) => "NAME" } }, sort: { name: "gsi1sk", definition: { build: (raw) => `NAME#${raw.name}` } } } },
   },
   client,
   autoTimestamps: true,
@@ -49,11 +50,24 @@ afterAll(async () => {
 describe('BetterDDB - Create Operation', () => {
   it('should insert an item using CreateBuilder', async () => {
     const user = { id: 'user-123', name: 'John Doe', email: 'john@example.com' };
+
     await userDdb.create(user as any).execute();
-    const createdUser = await userDdb.get({ id: 'user-123', email: 'john@example.com' }).execute();
-    expect(createdUser).not.toBeNull();
-    expect(createdUser?.id).toBe('user-123');
-    expect(createdUser).toHaveProperty('createdAt');
-    expect(createdUser).toHaveProperty('updatedAt');
+
+    const result = await client.get({ TableName: TEST_TABLE, Key: { id: 'user-123', email: 'john@example.com' } }).promise();
+
+    expect(result).not.toBeNull();
+    expect(result.Item).not.toBeNull();
+    expect(result.Item?.pk).toBe('USER#user-123');
+    expect(result.Item?.sk).toBe('EMAIL#john@example.com');
+    expect(result.Item?.gsi1pk).toBe('NAME');
+    expect(result.Item?.gsi1sk).toBe('NAME#John Doe');
+    expect(result.Item?.id).toBe('user-123');
+    expect(result.Item?.createdAt).not.toBeNull();
+    expect(result.Item?.updatedAt).not.toBeNull();
+  });
+
+  it('should fails to validate and not insert an item', async () => {
+    const user = { id: 'user-123', email: 'john@example.com' };
+    await expect(userDdb.create(user as any).execute()).rejects.toThrow();
   });
 });

package/test/delete.test.ts

@@ -25,7 +25,7 @@ const UserSchema = z.object({
   email: z.string().email(),
   createdAt: z.string(),
   updatedAt: z.string(),
-}).passthrough();
+});
 
 const userDdb = new BetterDDB({
   schema: UserSchema,

package/test/get.test.ts

@@ -26,7 +26,7 @@ const UserSchema = z.object({
   email: z.string().email(),
   createdAt: z.string(),
   updatedAt: z.string(),
-}).passthrough();
+});
 
 const userDdb = new BetterDDB({
   schema: UserSchema,

package/test/query.test.ts

@@ -24,7 +24,7 @@ const UserSchema = z.object({
   email: z.string().email(),
   createdAt: z.string(),
   updatedAt: z.string(),
-}).passthrough();
+});
 
 const userDdb = new BetterDDB({
   schema: UserSchema,

package/test/scan.test.ts

@@ -24,7 +24,7 @@ const UserSchema = z.object({
   email: z.string().email(),
   createdAt: z.string(),
   updatedAt: z.string(),
-}).passthrough();
+});
 
 const userDdb = new BetterDDB({
   schema: UserSchema,

package/test/update.test.ts

@@ -26,7 +26,7 @@ const UserSchema = z.object({
   createdAt: z.string(),
   updatedAt: z.string(),
   version: z.number().optional(),
-}).passthrough();
+});
 
 const userDdb = new BetterDDB({
   schema: UserSchema,