@nikovirtala/typesafe-dynamodb 0.0.1 → 0.0.2

package/README.md

@@ -1,17 +1,19 @@
-# typesafe-dynamodb
+# @nikovirtala/typesafe-dynamodb
 
-[![npm version](https://badge.fury.io/js/typesafe-dynamodb.svg)](https://badge.fury.io/js/typesafe-dynamodb)
+[![npm version](https://badge.fury.io/js/@nikovirtala%2Ftypesafe-dynamodb.svg)](https://badge.fury.io/js/@nikovirtala%2Ftypesafe-dynamodb)
 
-`typesafe-dynamodb` is a type-only library which replaces the type signatures of the AWS SDK v3's DynamoDB client. It substitutes `getItem`, `putItem`, `deleteItem` and `query` API methods with type-safe alternatives that are aware of the data in your tables and also adaptive to the semantics of the API request, e.g. by validating `ExpressionAttributeNames` and `ExpressionAttributeValues` contain all the values used in a `ConditionExpression` string, or by understanding the effect of a `ProjectionExpression` on the returned data type.
+`@nikovirtala/typesafe-dynamodb` is a fork of `typesafe-dynamodb` (a type-only library which replaces the type signatures of the AWS SDK v3's DynamoDB client) with schema validation based on [zod](https://zod.dev).
 
-The end goal is to provide types that have total understanding of the AWS DynamoDB API and enable full utilization of the TypeScript type system for modeling complex DynamoDB tables, such as the application of union types and template string literals for single-table designs.
+It substitutes `getItem`, `putItem`, `deleteItem` and `query` API methods with type-safe and schema validated alternatives that are aware of the data in your tables and also adaptive to the semantics of the API request, e.g. by validating `ExpressionAttributeNames` and `ExpressionAttributeValues` contain all the values used in a `ConditionExpression` string, or by understanding the effect of a `ProjectionExpression` on the returned data type.
+
+The end goal is to provide types and validation that have total understanding of the AWS DynamoDB API and enable full utilization of the TypeScript type system for modeling complex DynamoDB Tables, such as the application of union types and template string literals for single-table designs without forgetting runtime safety.
 
 ![typesafe putItem ConditionExpression](img/put-item-expression.gif)
 
 ## Installation
 
 ```
-npm install --save-dev typesafe-dynamodb
+npm install --save-dev @nikovirtala/typesafe-dynamodb
 ```
 
 ## Usage
@@ -108,7 +110,7 @@ import { TypeSafeDocumentClientV3 } from "typesafe-dynamodb/lib/document-client-
 const client = new DynamoDBClient({});
 
 const docClient = DynamoDBDocumentClient.from(
-  client
+  client,
 ) as TypeSafeDocumentClientV3<MyType, "key", "sort">;
 ```
 
@@ -134,7 +136,7 @@ Same for the `Item` in the response:
 
 ### Single Table Design
 
-Below are two `interface` declarations, representing two types of data stored in a single DynamoDB table - `User` and `Order`. Single table design in DynamoDB is achieved by creating "composite keys", e.g. `USER#${UserID}`. In TypeScript, we use template literal types to encode this in the Type System.
+Below are two `interface` declarations, representing two types of data stored in a single DynamoDB Table - `User` and `Order`. Single table design in DynamoDB is achieved by creating "composite keys", e.g. `USER#${UserID}`. In TypeScript, we use template literal types to encode this in the Type System.
 
 ```ts
 interface User<UserID extends string = string> {
@@ -149,7 +151,7 @@ interface User<UserID extends string = string> {
 
 interface Order<
   UserID extends string = string,
-  OrderID extends string = string
+  OrderID extends string = string,
 > {
   PK: `USER#${UserID}`;
   SK: `ORDER#${OrderID}`;
@@ -187,6 +189,41 @@ export async function handle(
 
 The event's type is derived from the data type and the the `StreamViewType`, e.g. `"NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY" | "NEW_AND_OLD_IMAGES"`.
 
+### Schema-Validated DynamoDBStreamEvent
+
+Validate DynamoDB stream events at runtime using Zod schemas:
+
+```ts
+import { z } from "zod";
+import { validateStreamEvent } from "typesafe-dynamodb";
+import type { DynamoDBStreamEvent } from "typesafe-dynamodb/lib/stream-event";
+
+const UserSchema = z.object({
+  PK: z.string(),
+  SK: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+export async function handle(
+  event: DynamoDBStreamEvent<User, "PK", "SK", "NEW_AND_OLD_IMAGES">,
+) {
+  try {
+    const validatedEvent = validateStreamEvent(event, UserSchema);
+    // Process validated stream records
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("Schema validation failed:", error.issues);
+    }
+    throw error;
+  }
+}
+```
+
+The `validateStreamEvent` function validates both `NewImage` and `OldImage` data against your Zod schema, ensuring runtime type safety for your stream processing logic.
+
 ### Filter result with ProjectionExpression
 
 The `ProjectionExpression` field is parsed and applied to filter the returned type of `getItem` and `query`.
@@ -293,4 +330,4 @@ const unmarshalled: {
   readonly list: readonly [...];
   readonly record: Unmarshall<...>;
 };
-```
+```

package/examples/schema-validated-delete-document.ts

@@ -0,0 +1,63 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { z } from "zod";
+import { SchemaValidatedDocumentClient } from "../src/schema-validated-document-client";
+import { SchemaValidatedDeleteDocumentCommand } from "../src/schema-validated-delete-document-command";
+
+const UserSchema = z.object({
+  pk: z.templateLiteral(["USER", "#", z.uuid()]),
+  sk: z.literal("METADATA"),
+  userId: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  age: z.number().min(0),
+  preferences: z.object({
+    theme: z.enum(["light", "dark"]),
+    notifications: z.boolean(),
+  }),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+const client = new DynamoDBClient({ region: "eu-west-1" });
+const documentClient = DynamoDBDocumentClient.from(client);
+const schemaValidatedDocumentClient = new SchemaValidatedDocumentClient(
+  documentClient,
+);
+
+const DeleteUserCommand = SchemaValidatedDeleteDocumentCommand<
+  User,
+  "pk",
+  "sk"
+>(UserSchema);
+
+async function deleteUserDocumentExample() {
+  try {
+    const result = await schemaValidatedDocumentClient.send(
+      new DeleteUserCommand({
+        TableName: "Users",
+        Key: {
+          pk: "USER#00000000-0000-0000-0000-000000000000",
+          sk: "METADATA",
+        },
+        ConditionExpression: "attribute_exists(pk)",
+        ReturnValues: "ALL_OLD",
+      }),
+      UserSchema,
+    );
+
+    if (result.Attributes) {
+      console.log("Deleted user:", result.Attributes);
+      return result.Attributes;
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("Schema validation failed:", error.issues);
+    } else {
+      console.error("DynamoDB error:", error);
+    }
+    throw error;
+  }
+}
+
+export { deleteUserDocumentExample, UserSchema };

package/examples/schema-validated-get-document.ts

@@ -0,0 +1,59 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { z } from "zod";
+import { SchemaValidatedDocumentClient } from "../src/schema-validated-document-client";
+import { SchemaValidatedGetDocumentCommand } from "../src/schema-validated-get-document-command";
+
+const UserSchema = z.object({
+  pk: z.templateLiteral(["USER", "#", z.uuid()]),
+  sk: z.literal("METADATA"),
+  userId: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  age: z.number().min(0),
+  preferences: z.object({
+    theme: z.enum(["light", "dark"]),
+    notifications: z.boolean(),
+  }),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+const client = new DynamoDBClient({ region: "eu-west-1" });
+const documentClient = DynamoDBDocumentClient.from(client);
+const schemaValidatedDocumentClient = new SchemaValidatedDocumentClient(
+  documentClient,
+);
+
+const GetUserCommand = SchemaValidatedGetDocumentCommand<User, "pk", "sk">(
+  UserSchema,
+);
+
+async function getUserDocumentExample() {
+  try {
+    const result = await schemaValidatedDocumentClient.send(
+      new GetUserCommand({
+        TableName: "Users",
+        Key: {
+          pk: "USER#00000000-0000-0000-0000-000000000000",
+          sk: "METADATA",
+        },
+      }),
+      UserSchema,
+    );
+
+    if (result.Item) {
+      console.log("Validated user:", result.Item);
+      return result.Item;
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("Schema validation failed:", error.issues);
+    } else {
+      console.error("DynamoDB error:", error);
+    }
+    throw error;
+  }
+}
+
+export { getUserDocumentExample, UserSchema };

package/examples/schema-validated-put-document.ts

@@ -0,0 +1,64 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { z } from "zod";
+import { SchemaValidatedDocumentClient } from "../src/schema-validated-document-client";
+import { SchemaValidatedPutDocumentCommand } from "../src/schema-validated-put-document-command";
+
+const UserSchema = z.object({
+  pk: z.templateLiteral(["USER", "#", z.uuid()]),
+  sk: z.literal("METADATA"),
+  userId: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  age: z.number().min(0),
+  preferences: z.object({
+    theme: z.enum(["light", "dark"]),
+    notifications: z.boolean(),
+  }),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+const client = new DynamoDBClient({ region: "eu-west-1" });
+const documentClient = DynamoDBDocumentClient.from(client);
+const schemaValidatedDocumentClient = new SchemaValidatedDocumentClient(
+  documentClient,
+);
+
+const PutUserCommand = SchemaValidatedPutDocumentCommand<User>(UserSchema);
+
+async function putUserDocumentExample() {
+  try {
+    const result = await schemaValidatedDocumentClient.send(
+      new PutUserCommand({
+        TableName: "Users",
+        Item: {
+          pk: "USER#00000000-0000-0000-0000-000000000000",
+          sk: "METADATA",
+          userId: "user123",
+          email: "user@example.com",
+          name: "John Doe",
+          age: 30,
+          preferences: {
+            theme: "dark",
+            notifications: true,
+          },
+        },
+        ConditionExpression: "attribute_not_exists(pk)",
+      }),
+      UserSchema,
+    );
+
+    console.log("User created successfully:", result);
+    return result;
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("Schema validation failed:", error.issues);
+    } else {
+      console.error("DynamoDB error:", error);
+    }
+    throw error;
+  }
+}
+
+export { putUserDocumentExample, UserSchema };

package/examples/schema-validated-query-document.ts

@@ -0,0 +1,69 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { z } from "zod";
+import { SchemaValidatedDocumentClient } from "../src/schema-validated-document-client";
+import { SchemaValidatedQueryDocumentCommand } from "../src/schema-validated-query-document-command";
+
+const OrderSchema = z.object({
+  pk: z.templateLiteral(["USER", "#", z.uuid()]),
+  sk: z.templateLiteral(["ORDER", "#", z.string()]),
+  userId: z.string(),
+  orderId: z.string(),
+  status: z.enum(["PLACED", "SHIPPED", "DELIVERED"]),
+  amount: z.number().min(0),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().min(1),
+      price: z.number().min(0),
+    }),
+  ),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+const client = new DynamoDBClient({ region: "eu-west-1" });
+const documentClient = DynamoDBDocumentClient.from(client);
+const schemaValidatedDocumentClient = new SchemaValidatedDocumentClient(
+  documentClient,
+);
+
+const QueryOrdersCommand =
+  SchemaValidatedQueryDocumentCommand<Order>(OrderSchema);
+
+async function queryUserOrdersExample() {
+  try {
+    const result = await schemaValidatedDocumentClient.send(
+      new QueryOrdersCommand({
+        TableName: "Orders",
+        KeyConditionExpression:
+          "pk = :userId AND begins_with(sk, :orderPrefix)",
+        FilterExpression: "#status = :status",
+        ExpressionAttributeNames: {
+          "#status": "status",
+        },
+        ExpressionAttributeValues: {
+          ":userId": "USER#00000000-0000-0000-0000-000000000000",
+          ":orderPrefix": "ORDER#",
+          ":status": "SHIPPED",
+        },
+      }),
+      OrderSchema,
+    );
+
+    if (result.Items) {
+      console.log("Validated orders:", result.Items);
+      return result.Items;
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("Schema validation failed:", error.issues);
+    } else {
+      console.error("DynamoDB error:", error);
+    }
+    throw error;
+  }
+}
+
+export { queryUserOrdersExample, OrderSchema };

package/examples/schema-validated-scan-document.ts

@@ -0,0 +1,57 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { z } from "zod";
+import { SchemaValidatedDocumentClient } from "../src/schema-validated-document-client";
+import { SchemaValidatedScanDocumentCommand } from "../src/schema-validated-scan-document-command";
+
+const UserSchema = z.object({
+  pk: z.templateLiteral(["USER", "#", z.uuid()]),
+  sk: z.literal("METADATA"),
+  userId: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  age: z.number().min(0),
+  preferences: z.object({
+    theme: z.enum(["light", "dark"]),
+    notifications: z.boolean(),
+  }),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+const client = new DynamoDBClient({ region: "eu-west-1" });
+const documentClient = DynamoDBDocumentClient.from(client);
+const schemaValidatedDocumentClient = new SchemaValidatedDocumentClient(
+  documentClient,
+);
+
+const ScanUsersCommand = SchemaValidatedScanDocumentCommand<User>(UserSchema);
+
+async function scanUsersDocumentExample() {
+  try {
+    const result = await schemaValidatedDocumentClient.send(
+      new ScanUsersCommand({
+        TableName: "Users",
+        FilterExpression: "age > :minAge",
+        ExpressionAttributeValues: {
+          ":minAge": 18,
+        },
+      }),
+      UserSchema,
+    );
+
+    if (result.Items) {
+      console.log("Validated users:", result.Items);
+      return result.Items;
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("Schema validation failed:", error.issues);
+    } else {
+      console.error("DynamoDB error:", error);
+    }
+    throw error;
+  }
+}
+
+export { scanUsersDocumentExample, UserSchema };

package/examples/schema-validated-stream-event.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { validateStreamEvent } from "../src/schema-validated-stream-event";
+import type { DynamoDBStreamEvent } from "../src/stream-event";
+
+const UserSchema = z.object({
+  pk: z.templateLiteral(["USER", "#", z.string()]),
+  sk: z.literal("PROFILE"),
+  userId: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  age: z.number().min(0),
+  preferences: z.object({
+    theme: z.enum(["light", "dark"]),
+    notifications: z.boolean(),
+  }),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+export async function handleUserStreamEvent(
+  event: DynamoDBStreamEvent<User, "pk", "sk", "NEW_AND_OLD_IMAGES">,
+) {
+  try {
+    const validatedEvent = validateStreamEvent(event, UserSchema);
+
+    for (const record of validatedEvent.Records) {
+      console.log(`Processing ${record.eventName} event for ${record.eventID}`);
+
+      if (record.dynamodb?.NewImage) {
+        console.log("New user data validated successfully");
+      }
+
+      if (record.dynamodb?.OldImage) {
+        console.log("Old user data validated successfully");
+      }
+
+      switch (record.eventName) {
+        case "INSERT":
+          console.log("User created");
+          break;
+        case "MODIFY":
+          console.log("User updated");
+          break;
+        case "REMOVE":
+          console.log("User deleted");
+          break;
+      }
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("Schema validation failed:", error.issues);
+      throw new Error(`Invalid stream data: ${error.message}`);
+    } else {
+      console.error("Stream processing error:", error);
+      throw error;
+    }
+  }
+}
+
+export { UserSchema };

package/examples/schema-validated-update-document.ts

@@ -0,0 +1,75 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { z } from "zod";
+import { SchemaValidatedDocumentClient } from "../src/schema-validated-document-client";
+import { SchemaValidatedUpdateDocumentCommand } from "../src/schema-validated-update-document-command";
+
+const UserSchema = z.object({
+  pk: z.templateLiteral(["USER", "#", z.uuid()]),
+  sk: z.literal("METADATA"),
+  userId: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  age: z.number().min(0),
+  preferences: z.object({
+    theme: z.enum(["light", "dark"]),
+    notifications: z.boolean(),
+  }),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+const client = new DynamoDBClient({ region: "eu-west-1" });
+const documentClient = DynamoDBDocumentClient.from(client);
+const schemaValidatedDocumentClient = new SchemaValidatedDocumentClient(
+  documentClient,
+);
+
+const UpdateUserCommand = SchemaValidatedUpdateDocumentCommand<
+  User,
+  "pk",
+  "sk"
+>(UserSchema);
+
+async function updateUserDocumentExample() {
+  try {
+    const result = await schemaValidatedDocumentClient.send(
+      new UpdateUserCommand({
+        TableName: "Users",
+        Key: {
+          pk: "USER#00000000-0000-0000-0000-000000000000",
+          sk: "METADATA",
+        },
+        UpdateExpression:
+          "SET #name = :name, #age = :age, #preferences.#theme = :theme",
+        ExpressionAttributeNames: {
+          "#name": "name",
+          "#age": "age",
+          "#preferences": "preferences",
+          "#theme": "theme",
+        },
+        ExpressionAttributeValues: {
+          ":name": "John Doe",
+          ":age": 30,
+          ":theme": "dark",
+        },
+        ReturnValues: "ALL_NEW",
+      }),
+      UserSchema,
+    );
+
+    if (result.Attributes) {
+      console.log("Updated user:", result.Attributes);
+      return result.Attributes;
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error("Schema validation failed:", error.issues);
+    } else {
+      console.error("DynamoDB error:", error);
+    }
+    throw error;
+  }
+}
+
+export { updateUserDocumentExample, UserSchema };

package/lib/schema-validated-delete-document-command.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+import type { DeleteCommand } from "./delete-item";
+import type { JsonFormat } from "./json-format";
+export declare function SchemaValidatedDeleteDocumentCommand<Item extends object, PartitionKey extends keyof Item, RangeKey extends keyof Item | undefined>(schema: z.ZodSchema<Item>): DeleteCommand<Item, PartitionKey, RangeKey, JsonFormat.Document> & {
+    _schema: z.ZodSchema<Item>;
+};

package/lib/schema-validated-delete-document-command.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaValidatedDeleteDocumentCommand = SchemaValidatedDeleteDocumentCommand;
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+function SchemaValidatedDeleteDocumentCommand(schema) {
+    const Command = lib_dynamodb_1.DeleteCommand;
+    Command._schema = schema;
+    return Command;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hLXZhbGlkYXRlZC1kZWxldGUtZG9jdW1lbnQtY29tbWFuZC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9zY2hlbWEtdmFsaWRhdGVkLWRlbGV0ZS1kb2N1bWVudC1jb21tYW5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBS0Esb0ZBWUM7QUFqQkQsd0RBQXdFO0FBS3hFLFNBQWdCLG9DQUFvQyxDQUtsRCxNQUF5QjtJQUl6QixNQUFNLE9BQU8sR0FBRyw0QkFBcUIsQ0FBQztJQUN0QyxPQUFPLENBQUMsT0FBTyxHQUFHLE1BQU0sQ0FBQztJQUN6QixPQUFPLE9BQU8sQ0FBQztBQUNqQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgRGVsZXRlQ29tbWFuZCBhcyBfRGVsZXRlQ29tbWFuZCB9IGZyb20gXCJAYXdzLXNkay9saWItZHluYW1vZGJcIjtcbmltcG9ydCB7IHogfSBmcm9tIFwiem9kXCI7XG5pbXBvcnQgdHlwZSB7IERlbGV0ZUNvbW1hbmQgfSBmcm9tIFwiLi9kZWxldGUtaXRlbVwiO1xuaW1wb3J0IHR5cGUgeyBKc29uRm9ybWF0IH0gZnJvbSBcIi4vanNvbi1mb3JtYXRcIjtcblxuZXhwb3J0IGZ1bmN0aW9uIFNjaGVtYVZhbGlkYXRlZERlbGV0ZURvY3VtZW50Q29tbWFuZDxcbiAgSXRlbSBleHRlbmRzIG9iamVjdCxcbiAgUGFydGl0aW9uS2V5IGV4dGVuZHMga2V5b2YgSXRlbSxcbiAgUmFuZ2VLZXkgZXh0ZW5kcyBrZXlvZiBJdGVtIHwgdW5kZWZpbmVkLFxuPihcbiAgc2NoZW1hOiB6LlpvZFNjaGVtYTxJdGVtPixcbik6IERlbGV0ZUNvbW1hbmQ8SXRlbSwgUGFydGl0aW9uS2V5LCBSYW5nZUtleSwgSnNvbkZvcm1hdC5Eb2N1bWVudD4gJiB7XG4gIF9zY2hlbWE6IHouWm9kU2NoZW1hPEl0ZW0+O1xufSB7XG4gIGNvbnN0IENvbW1hbmQgPSBfRGVsZXRlQ29tbWFuZCBhcyBhbnk7XG4gIENvbW1hbmQuX3NjaGVtYSA9IHNjaGVtYTtcbiAgcmV0dXJuIENvbW1hbmQ7XG59XG4iXX0=

package/lib/schema-validated-document-client.d.ts

@@ -0,0 +1,35 @@
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { z } from "zod";
+export declare class SchemaValidatedDocumentClient {
+    private client;
+    constructor(client: DynamoDBDocumentClient);
+    send<T, Item extends object>(command: T, schema?: z.ZodSchema<Item>): Promise<T extends {
+        _brand: "UpdateItemCommand";
+    } ? {
+        Attributes?: Item;
+        $metadata: any;
+    } : T extends {
+        _brand: "DeleteItemCommand";
+    } ? {
+        Attributes?: Item;
+        $metadata: any;
+    } : T extends {
+        _brand: "PutItemCommand";
+    } ? {
+        Attributes?: Item;
+        $metadata: any;
+    } : T extends {
+        _brand: "GetItemCommand";
+    } ? {
+        Item?: Item;
+        $metadata: any;
+    } : T extends {
+        _brand: "QueryCommand" | "ScanCommand";
+    } ? {
+        Items?: Item[];
+        $metadata: any;
+        Count?: number;
+        ScannedCount?: number;
+        LastEvaluatedKey?: any;
+    } : Awaited<ReturnType<DynamoDBDocumentClient["send"]>>>;
+}

package/lib/schema-validated-document-client.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaValidatedDocumentClient = void 0;
+class SchemaValidatedDocumentClient {
+    constructor(client) {
+        this.client = client;
+    }
+    async send(command, schema) {
+        const result = await this.client.send(command);
+        if (schema) {
+            if ("Item" in result && result.Item) {
+                result.Item = schema.parse(result.Item);
+            }
+            if ("Attributes" in result && result.Attributes) {
+                result.Attributes = schema.parse(result.Attributes);
+            }
+            if ("Items" in result && result.Items) {
+                result.Items = result.Items.map((item) => schema.parse(item));
+            }
+        }
+        return result;
+    }
+}
+exports.SchemaValidatedDocumentClient = SchemaValidatedDocumentClient;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hLXZhbGlkYXRlZC1kb2N1bWVudC1jbGllbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvc2NoZW1hLXZhbGlkYXRlZC1kb2N1bWVudC1jbGllbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBR0EsTUFBYSw2QkFBNkI7SUFDeEMsWUFBb0IsTUFBOEI7UUFBOUIsV0FBTSxHQUFOLE1BQU0sQ0FBd0I7SUFBRyxDQUFDO0lBRXRELEtBQUssQ0FBQyxJQUFJLENBQ1IsT0FBVSxFQUNWLE1BQTBCO1FBb0IxQixNQUFNLE1BQU0sR0FBRyxNQUFNLElBQUksQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLE9BQWMsQ0FBQyxDQUFDO1FBRXRELElBQUksTUFBTSxFQUFFLENBQUM7WUFDWCxJQUFJLE1BQU0sSUFBSSxNQUFNLElBQUksTUFBTSxDQUFDLElBQUksRUFBRSxDQUFDO2dCQUNuQyxNQUFjLENBQUMsSUFBSSxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxDQUFDO1lBQ25ELENBQUM7WUFFRCxJQUFJLFlBQVksSUFBSSxNQUFNLElBQUksTUFBTSxDQUFDLFVBQVUsRUFBRSxDQUFDO2dCQUMvQyxNQUFjLENBQUMsVUFBVSxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsTUFBTSxDQUFDLFVBQVUsQ0FBQyxDQUFDO1lBQy9ELENBQUM7WUFFRCxJQUFJLE9BQU8sSUFBSSxNQUFNLElBQUksTUFBTSxDQUFDLEtBQUssRUFBRSxDQUFDO2dCQUNyQyxNQUFjLENBQUMsS0FBSyxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLENBQUMsSUFBUyxFQUFFLEVBQUUsQ0FDckQsTUFBTSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsQ0FDbkIsQ0FBQztZQUNKLENBQUM7UUFDSCxDQUFDO1FBRUQsT0FBTyxNQUFhLENBQUM7SUFDdkIsQ0FBQztDQUNGO0FBN0NELHNFQTZDQyIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IER5bmFtb0RCRG9jdW1lbnRDbGllbnQgfSBmcm9tIFwiQGF3cy1zZGsvbGliLWR5bmFtb2RiXCI7XG5pbXBvcnQgeyB6IH0gZnJvbSBcInpvZFwiO1xuXG5leHBvcnQgY2xhc3MgU2NoZW1hVmFsaWRhdGVkRG9jdW1lbnRDbGllbnQge1xuICBjb25zdHJ1Y3Rvcihwcml2YXRlIGNsaWVudDogRHluYW1vREJEb2N1bWVudENsaWVudCkge31cblxuICBhc3luYyBzZW5kPFQsIEl0ZW0gZXh0ZW5kcyBvYmplY3Q+KFxuICAgIGNvbW1hbmQ6IFQsXG4gICAgc2NoZW1hPzogei5ab2RTY2hlbWE8SXRlbT4sXG4gICk6IFByb21pc2U8XG4gICAgVCBleHRlbmRzIHsgX2JyYW5kOiBcIlVwZGF0ZUl0ZW1Db21tYW5kXCIgfVxuICAgICAgPyB7IEF0dHJpYnV0ZXM/OiBJdGVtOyAkbWV0YWRhdGE6IGFueSB9XG4gICAgICA6IFQgZXh0ZW5kcyB7IF9icmFuZDogXCJEZWxldGVJdGVtQ29tbWFuZFwiIH1cbiAgICAgICAgPyB7IEF0dHJpYnV0ZXM/OiBJdGVtOyAkbWV0YWRhdGE6IGFueSB9XG4gICAgICAgIDogVCBleHRlbmRzIHsgX2JyYW5kOiBcIlB1dEl0ZW1Db21tYW5kXCIgfVxuICAgICAgICAgID8geyBBdHRyaWJ1dGVzPzogSXRlbTsgJG1ldGFkYXRhOiBhbnkgfVxuICAgICAgICAgIDogVCBleHRlbmRzIHsgX2JyYW5kOiBcIkdldEl0ZW1Db21tYW5kXCIgfVxuICAgICAgICAgICAgPyB7IEl0ZW0/OiBJdGVtOyAkbWV0YWRhdGE6IGFueSB9XG4gICAgICAgICAgICA6IFQgZXh0ZW5kcyB7IF9icmFuZDogXCJRdWVyeUNvbW1hbmRcIiB8IFwiU2NhbkNvbW1hbmRcIiB9XG4gICAgICAgICAgICAgID8ge1xuICAgICAgICAgICAgICAgICAgSXRlbXM/OiBJdGVtW107XG4gICAgICAgICAgICAgICAgICAkbWV0YWRhdGE6IGFueTtcbiAgICAgICAgICAgICAgICAgIENvdW50PzogbnVtYmVyO1xuICAgICAgICAgICAgICAgICAgU2Nhbm5lZENvdW50PzogbnVtYmVyO1xuICAgICAgICAgICAgICAgICAgTGFzdEV2YWx1YXRlZEtleT86IGFueTtcbiAgICAgICAgICAgICAgICB9XG4gICAgICAgICAgICAgIDogQXdhaXRlZDxSZXR1cm5UeXBlPER5bmFtb0RCRG9jdW1lbnRDbGllbnRbXCJzZW5kXCJdPj5cbiAgPiB7XG4gICAgY29uc3QgcmVzdWx0ID0gYXdhaXQgdGhpcy5jbGllbnQuc2VuZChjb21tYW5kIGFzIGFueSk7XG5cbiAgICBpZiAoc2NoZW1hKSB7XG4gICAgICBpZiAoXCJJdGVtXCIgaW4gcmVzdWx0ICYmIHJlc3VsdC5JdGVtKSB7XG4gICAgICAgIChyZXN1bHQgYXMgYW55KS5JdGVtID0gc2NoZW1hLnBhcnNlKHJlc3VsdC5JdGVtKTtcbiAgICAgIH1cblxuICAgICAgaWYgKFwiQXR0cmlidXRlc1wiIGluIHJlc3VsdCAmJiByZXN1bHQuQXR0cmlidXRlcykge1xuICAgICAgICAocmVzdWx0IGFzIGFueSkuQXR0cmlidXRlcyA9IHNjaGVtYS5wYXJzZShyZXN1bHQuQXR0cmlidXRlcyk7XG4gICAgICB9XG5cbiAgICAgIGlmIChcIkl0ZW1zXCIgaW4gcmVzdWx0ICYmIHJlc3VsdC5JdGVtcykge1xuICAgICAgICAocmVzdWx0IGFzIGFueSkuSXRlbXMgPSByZXN1bHQuSXRlbXMubWFwKChpdGVtOiBhbnkpID0+XG4gICAgICAgICAgc2NoZW1hLnBhcnNlKGl0ZW0pLFxuICAgICAgICApO1xuICAgICAgfVxuICAgIH1cblxuICAgIHJldHVybiByZXN1bHQgYXMgYW55O1xuICB9XG59XG4iXX0=

package/lib/schema-validated-get-document-command.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+import type { GetCommand } from "./get-command";
+import type { JsonFormat } from "./json-format";
+export declare function SchemaValidatedGetDocumentCommand<Item extends object, PartitionKey extends keyof Item, RangeKey extends keyof Item | undefined>(schema: z.ZodSchema<Item>): GetCommand<Item, PartitionKey, RangeKey, JsonFormat.Document> & {
+    _schema: z.ZodSchema<Item>;
+};

package/lib/schema-validated-get-document-command.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaValidatedGetDocumentCommand = SchemaValidatedGetDocumentCommand;
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+function SchemaValidatedGetDocumentCommand(schema) {
+    const Command = lib_dynamodb_1.GetCommand;
+    Command._schema = schema;
+    return Command;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hLXZhbGlkYXRlZC1nZXQtZG9jdW1lbnQtY29tbWFuZC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9zY2hlbWEtdmFsaWRhdGVkLWdldC1kb2N1bWVudC1jb21tYW5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBS0EsOEVBWUM7QUFqQkQsd0RBQWtFO0FBS2xFLFNBQWdCLGlDQUFpQyxDQUsvQyxNQUF5QjtJQUl6QixNQUFNLE9BQU8sR0FBRyx5QkFBa0IsQ0FBQztJQUNuQyxPQUFPLENBQUMsT0FBTyxHQUFHLE1BQU0sQ0FBQztJQUN6QixPQUFPLE9BQU8sQ0FBQztBQUNqQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgR2V0Q29tbWFuZCBhcyBfR2V0Q29tbWFuZCB9IGZyb20gXCJAYXdzLXNkay9saWItZHluYW1vZGJcIjtcbmltcG9ydCB7IHogfSBmcm9tIFwiem9kXCI7XG5pbXBvcnQgdHlwZSB7IEdldENvbW1hbmQgfSBmcm9tIFwiLi9nZXQtY29tbWFuZFwiO1xuaW1wb3J0IHR5cGUgeyBKc29uRm9ybWF0IH0gZnJvbSBcIi4vanNvbi1mb3JtYXRcIjtcblxuZXhwb3J0IGZ1bmN0aW9uIFNjaGVtYVZhbGlkYXRlZEdldERvY3VtZW50Q29tbWFuZDxcbiAgSXRlbSBleHRlbmRzIG9iamVjdCxcbiAgUGFydGl0aW9uS2V5IGV4dGVuZHMga2V5b2YgSXRlbSxcbiAgUmFuZ2VLZXkgZXh0ZW5kcyBrZXlvZiBJdGVtIHwgdW5kZWZpbmVkLFxuPihcbiAgc2NoZW1hOiB6LlpvZFNjaGVtYTxJdGVtPixcbik6IEdldENvbW1hbmQ8SXRlbSwgUGFydGl0aW9uS2V5LCBSYW5nZUtleSwgSnNvbkZvcm1hdC5Eb2N1bWVudD4gJiB7XG4gIF9zY2hlbWE6IHouWm9kU2NoZW1hPEl0ZW0+O1xufSB7XG4gIGNvbnN0IENvbW1hbmQgPSBfR2V0Q29tbWFuZCBhcyBhbnk7XG4gIENvbW1hbmQuX3NjaGVtYSA9IHNjaGVtYTtcbiAgcmV0dXJuIENvbW1hbmQ7XG59XG4iXX0=

package/lib/schema-validated-put-document-command.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+import type { JsonFormat } from "./json-format";
+import type { PutCommand } from "./put-item";
+export declare function SchemaValidatedPutDocumentCommand<Item extends object>(schema: z.ZodSchema<Item>): PutCommand<Item, JsonFormat.Document> & {
+    _schema: z.ZodSchema<Item>;
+};