aws-sdk-vitest-mock 0.3.1 → 0.5.0

package/README.md

@@ -8,6 +8,24 @@
   A powerful, type-safe mocking library for AWS SDK v3 with Vitest
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/aws-sdk-vitest-mock">
+    <img src="https://img.shields.io/npm/v/aws-sdk-vitest-mock?color=cb3837&logo=npm" alt="npm version" />
+  </a>
+  <a href="https://github.com/sudokar/aws-sdk-vitest-mock/actions">
+      <img src="https://github.com/sudokar/aws-sdk-vitest-mock/actions/workflows/ci.yml/badge.svg" alt="CI Status" />
+  </a>
+  <img src="https://img.shields.io/badge/ESM%20Support-yes-4B32C3?logo=javascript" alt="ESM Support" />
+  <img src="https://img.shields.io/badge/Zero%20Dependencies-yes-brightgreen" alt="Zero Dependencies" />
+  <a href="https://eslint.org/">
+    <img src="https://img.shields.io/badge/code%20style-eslint-4B32C3?logo=eslint" alt="ESLint" />
+  </a>
+  <a href="https://prettier.io/">
+    <img src="https://img.shields.io/badge/code%20style-prettier-F7B93E?logo=prettier" alt="Prettier" />
+  </a>
+  <img src="https://img.shields.io/badge/Maintained-yes-brightgreen" alt="Maintained: Yes" />
+</p>
+
 ---
 
 ## ✨ Features
@@ -43,6 +61,8 @@ pnpm add -D aws-sdk-vitest-mock
 
 ### Basic Usage
 
+> **Note:** `mockClient()` mocks **all instances** of a client class. Use `mockClientInstance()` when you need to mock a specific instance.
+
 ```typescript
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { mockClient } from "aws-sdk-vitest-mock";
@@ -65,10 +85,10 @@ describe("DocumentService", () => {
   let documentService: DocumentService;
 
   beforeEach(() => {
-    // Mock the S3 client
+    // Mock all instances of S3Client
     s3Mock = mockClient(S3Client);
 
-    // Create service with real S3Client (which is now mocked)
+    // Any S3Client instance created after this will be mocked
     const s3Client = new S3Client({ region: "us-east-1" });
     documentService = new DocumentService(s3Client);
   });
@@ -93,6 +113,21 @@ describe("DocumentService", () => {
 });
 ```
 
+## 🎯 Key Concepts
+
+Understanding these concepts will help you use the library effectively:
+
+- **`mockClient(ClientClass)`** - Mocks **all instances** of a client class. Use this in most test scenarios where you control client creation.
+- **`mockClientInstance(instance)`** - Mocks a **specific client instance**. Use when the client is created outside your test (e.g., in application bootstrap).
+- **Command Matching** - Commands are matched by constructor. Optionally match by input properties (partial matching by default, strict matching available).
+- **Sequential Responses** - Use `resolvesOnce()` / `rejectsOnce()` for one-time behaviors that fall back to permanent handlers set with `resolves()` / `rejects()`.
+- **Chainable API** - All mock configuration methods return the stub, allowing method chaining for cleaner test setup.
+- **Test Lifecycle**:
+  - **`reset()`** - Clears call history while preserving mock configurations. Use when you want to verify multiple test scenarios with the same mock setup.
+  - **`restore()`** - Completely removes mocking and restores original client behavior. Use in `afterEach()` to clean up between tests.
+
+## 📖 Usage Guide
+
 ### Request Matching
 
 ```typescript
@@ -121,56 +156,99 @@ s3Mock
 // All other calls return 'subsequent calls'
 ```
 
-### Fixture Loading
-
-Load mock responses from files for easier test data management:
+### Error Handling
 
 ```typescript
-// Load JSON response from file
-s3Mock.on(GetObjectCommand).resolvesFromFile("./fixtures/s3-response.json");
+s3Mock.on(GetObjectCommand).rejects(new Error("Not found"));
 
-// Load text response from file
-s3Mock.on(GetObjectCommand).resolvesFromFile("./fixtures/response.txt");
+// Or with rejectsOnce
+s3Mock
+  .on(GetObjectCommand)
+  .rejectsOnce(new Error("Temporary failure"))
+  .resolves({ Body: "success" });
+```
 
-// JSON files are automatically parsed, text files returned as strings
-// File paths are resolved relative to current working directory
+### Custom Handlers
+
+```typescript
+s3Mock.on(GetObjectCommand).callsFake(async (input, getClient) => {
+  const client = getClient();
+  console.log("Bucket:", input.Bucket);
+  return { Body: `Dynamic response for ${input.Key}` };
+});
 ```
 
-### Paginator Support
+### Mocking Existing Instances
 
-Mock AWS SDK v3 pagination with automatic token handling:
+Use `mockClientInstance()` when you need to mock a client that's already been created:
 
 ```typescript
-// Mock DynamoDB scan with pagination
-const items = Array.from({ length: 25 }, (_, i) => ({
-  id: { S: `item-${i + 1}` },
-}));
+// Your application service that uses an injected S3 client
+class FileUploadService {
+  constructor(private s3Client: S3Client) {}
 
-dynamoMock.on(ScanCommand).resolvesPaginated(items, {
-  pageSize: 10,
-  itemsKey: "Items",
-  tokenKey: "NextToken",
+  async uploadFile(bucket: string, key: string, data: string) {
+    return await this.s3Client.send(
+      new PutObjectCommand({ Bucket: bucket, Key: key, Body: data }),
+    );
+  }
+}
+
+test("should mock existing S3 client instance", async () => {
+  // Client is already created (e.g., in application bootstrap)
+  const s3Client = new S3Client({ region: "us-east-1" });
+  const service = new FileUploadService(s3Client);
+
+  // Mock the specific client instance
+  const mock = mockClientInstance(s3Client);
+  mock.on(PutObjectCommand).resolves({ ETag: "mock-etag" });
+
+  // Test your service
+  const result = await service.uploadFile("bucket", "key", "data");
+
+  expect(result.ETag).toBe("mock-etag");
+  expect(mock).toHaveReceivedCommand(PutObjectCommand);
 });
+```
 
-// First call returns items 1-10 with NextToken
-// Second call with NextToken returns items 11-20
-// Third call returns items 21-25 without NextToken
+### Test Lifecycle Management
 
-// Mock S3 list objects with pagination
-const objects = Array.from({ length: 15 }, (_, i) => ({
-  Key: `file-${i + 1}.txt`,
-}));
+Use `reset()` to clear call history between assertions while keeping mock configurations. Use `restore()` to completely clean up mocking:
 
-s3Mock.on(ListObjectsV2Command).resolvesPaginated(objects, {
-  pageSize: 10,
-  itemsKey: "Contents",
-  tokenKey: "ContinuationToken",
+```typescript
+test("should handle multiple operations with same mock", async () => {
+  const s3Mock = mockClient(S3Client);
+  const client = new S3Client({});
+
+  // Configure mock once
+  s3Mock.on(GetObjectCommand).resolves({ Body: "file-content" });
+
+  // First operation
+  await client.send(
+    new GetObjectCommand({ Bucket: "bucket", Key: "file1.txt" }),
+  );
+  expect(s3Mock).toHaveReceivedCommandTimes(GetObjectCommand, 1);
+
+  // Reset clears call history but keeps mock configuration
+  s3Mock.reset();
+  expect(s3Mock).toHaveReceivedCommandTimes(GetObjectCommand, 0);
+
+  // Second operation - mock still works
+  await client.send(
+    new GetObjectCommand({ Bucket: "bucket", Key: "file2.txt" }),
+  );
+  expect(s3Mock).toHaveReceivedCommandTimes(GetObjectCommand, 1);
+
+  // Clean up completely
+  s3Mock.restore();
 });
 ```
 
+## 🔧 AWS Service Examples
+
 ### DynamoDB with Marshal/Unmarshal
 
-Mock DynamoDB operations using AWS SDK's marshal/unmarshal utilities for type-safe data handling:
+Mock DynamoDB operations using marshal/unmarshal utilities for type-safe data handling:
 
 ```typescript
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
@@ -265,7 +343,9 @@ describe("UserService with DynamoDB", () => {
 });
 ```
 
-### Stream Mocking (S3 Helper)
+## 🚀 Advanced Features
+
+### Stream Mocking (S3)
 
 Mock S3 operations that return streams with automatic environment detection:
 
@@ -283,21 +363,122 @@ s3Mock
   .resolvesStream("Subsequent calls");
 ```
 
-### Delay/Latency Simulation
+### Paginator Support
 
-Simulate network delays for testing timeouts and race conditions:
+Mock AWS SDK v3 pagination with automatic token handling. **Tokens are the actual last item from each page** (works for both DynamoDB and S3).
+
+#### DynamoDB Pagination
 
 ```typescript
-// Resolve with delay
-s3Mock.on(GetObjectCommand).resolvesWithDelay({ Body: "data" }, 1000);
+import { marshall, unmarshall } from '@aws-sdk/util-dynamodb';
+import { DynamoDBClient, ScanCommand } from '@aws-sdk/client-dynamodb';
 
-// Reject with delay
-s3Mock.on(GetObjectCommand).rejectsWithDelay("Network timeout", 500);
+// Create marshalled items (as they would be stored in DynamoDB)
+const users = [
+  { id: "user-1", name: "Alice", email: "alice@example.com" },
+  { id: "user-2", name: "Bob", email: "bob@example.com" },
+  { id: "user-3", name: "Charlie", email: "charlie@example.com" },
+];
+
+const marshalledUsers = users.map(user => marshall(user));
+
+// Configure pagination
+dynamoMock.on(ScanCommand).resolvesPaginated(marshalledUsers, {
+  pageSize: 1,
+  itemsKey: "Items",
+  tokenKey: "LastEvaluatedKey",      // DynamoDB response key
+  inputTokenKey: "ExclusiveStartKey"  // DynamoDB request key
+});
+
+// Page 1: Get first user
+const page1 = await client.send(new ScanCommand({ TableName: "Users" }));
+expect(page1.Items).toHaveLength(1);
+// LastEvaluatedKey is the marshalled last item (object, not string!)
+expect(page1.LastEvaluatedKey).toEqual(marshall({ id: "user-1", name: "Alice", ... }));
+
+// Unmarshall the items
+const page1Users = page1.Items.map(item => unmarshall(item));
+console.log(page1Users[0]); // { id: "user-1", name: "Alice", ... }
+
+// Page 2: Use LastEvaluatedKey to get next page
+const page2 = await client.send(
+  new ScanCommand({
+    TableName: "Users",
+    ExclusiveStartKey: page1.LastEvaluatedKey, // Pass the object directly
+  })
+);
+
+// Page 3: Continue until LastEvaluatedKey is undefined
+const page3 = await client.send(
+  new ScanCommand({
+    TableName: "Users",
+    ExclusiveStartKey: page2.LastEvaluatedKey,
+  })
+);
+expect(page3.LastEvaluatedKey).toBeUndefined(); // No more pages
 ```
 
+#### S3 Pagination
+
+```typescript
+import { S3Client, ListObjectsV2Command } from '@aws-sdk/client-s3';
+
+const objects = Array.from({ length: 100 }, (_, i) => ({
+  Key: `file-${i + 1}.txt`,
+  Size: 1024,
+  LastModified: new Date(),
+}));
+
+s3Mock.on(ListObjectsV2Command).resolvesPaginated(objects, {
+  pageSize: 50,
+  itemsKey: "Contents",
+  tokenKey: "NextContinuationToken",
+  inputTokenKey: "ContinuationToken"
+});
+
+// First page
+const page1 = await client.send(
+  new ListObjectsV2Command({ Bucket: "my-bucket" })
+);
+expect(page1.Contents).toHaveLength(50);
+// NextContinuationToken is the last object from page 1
+expect(page1.NextContinuationToken).toEqual({ Key: "file-50.txt", ... });
+
+// Second page
+const page2 = await client.send(
+  new ListObjectsV2Command({
+    Bucket: "my-bucket",
+    ContinuationToken: page1.NextContinuationToken,
+  })
+);
+expect(page2.Contents).toHaveLength(50);
+expect(page2.NextContinuationToken).toBeUndefined(); // No more pages
+```
+
+**Pagination Options:**
+
+- `pageSize` - Number of items per page (default: 10)
+- `itemsKey` - Property name for items array in response (default: "Items")
+- `tokenKey` - Property name for pagination token in response (default: "NextToken")
+  - DynamoDB: use `"LastEvaluatedKey"`
+  - S3: use `"NextContinuationToken"`
+- `inputTokenKey` - Property name for pagination token in request (defaults to same as tokenKey)
+  - DynamoDB: use `"ExclusiveStartKey"`
+  - S3: use `"ContinuationToken"`
+
+**How It Works:**
+
+The mock automatically uses the **last item from each page** as the pagination token. This means:
+
+- ✅ For DynamoDB: `LastEvaluatedKey` is a proper object (can be unmarshalled)
+- ✅ For S3: `NextContinuationToken` is the last object
+- ✅ Tokens represent actual data, not opaque strings
+- ✅ Works correctly with `unmarshall()` for DynamoDB
+  - Use this when AWS service uses different names for input/output tokens (e.g., DynamoDB's `ExclusiveStartKey` vs `LastEvaluatedKey`)
+
 ### AWS Error Simulation
 
-Convenient methods for common AWS errors:
+Convenient helper methods for common AWS errors:
 
 ```typescript
 // S3 Errors
@@ -314,62 +495,33 @@ s3Mock.on(GetObjectCommand).rejectsWithThrottling();
 s3Mock.on(GetObjectCommand).rejectsWithInternalServerError();
 ```
 
-### Error Handling
+### Delay/Latency Simulation
+
+Simulate network delays for testing timeouts and race conditions:
 
 ```typescript
-s3Mock.on(GetObjectCommand).rejects(new Error("Not found"));
+// Resolve with delay
+s3Mock.on(GetObjectCommand).resolvesWithDelay({ Body: "data" }, 1000);
 
-// Or with rejectsOnce
-s3Mock
-  .on(GetObjectCommand)
-  .rejectsOnce(new Error("Temporary failure"))
-  .resolves({ Body: "success" });
+// Reject with delay
+s3Mock.on(GetObjectCommand).rejectsWithDelay("Network timeout", 500);
 ```
 
-### Custom Handlers
-
-```typescript
-s3Mock.on(GetObjectCommand).callsFake(async (input, getClient) => {
-  const client = getClient();
-  console.log("Bucket:", input.Bucket);
-  return { Body: `Dynamic response for ${input.Key}` };
-});
-```
+### Fixture Loading
 
-### Mocking Existing Instances
+Load mock responses from files for easier test data management:
 
 ```typescript
-// Your application service that uses an injected S3 client
-class FileUploadService {
-  constructor(private s3Client: S3Client) {}
-
-  async uploadFile(bucket: string, key: string, data: string) {
-    return await this.s3Client.send(
-      new PutObjectCommand({ Bucket: bucket, Key: key, Body: data }),
-    );
-  }
-}
-
-test("should mock existing S3 client instance", async () => {
-  // Create the client your application will use
-  const s3Client = new S3Client({ region: "us-east-1" });
-  const service = new FileUploadService(s3Client);
-
-  // Mock the existing client instance
-  const mock = mockClientInstance(s3Client);
-  mock.on(PutObjectCommand).resolves({ ETag: "mock-etag" });
-
-  // Test your service
-  const result = await service.uploadFile("bucket", "key", "data");
+// Load JSON response from file (automatically parsed)
+s3Mock.on(GetObjectCommand).resolvesFromFile("./fixtures/s3-response.json");
 
-  expect(result.ETag).toBe("mock-etag");
-  expect(mock).toHaveReceivedCommand(PutObjectCommand);
-});
+// Load text response from file (returned as string)
+s3Mock.on(GetObjectCommand).resolvesFromFile("./fixtures/response.txt");
 ```
 
 ### Debug Mode
 
-Enable debug logging to troubleshoot mock configurations and see detailed information about command matching:
+Enable debug logging to see detailed information about mock configuration, lifecycle events, and command interactions:
 
 ```typescript
 const s3Mock = mockClient(S3Client);
@@ -377,29 +529,62 @@ const s3Mock = mockClient(S3Client);
 // Enable debug logging
 s3Mock.enableDebug();
 
+// Configuration logs appear immediately:
+// [aws-sdk-vitest-mock](Debug) Configured resolves for GetObjectCommand
+// {
+//   "matcher": {
+//     "Bucket": "test-bucket"
+//   },
+//   "strict": false
+// }
 s3Mock
   .on(GetObjectCommand, { Bucket: "test-bucket" })
   .resolves({ Body: "data" });
 
-// This will log:
-// [AWS Mock Debug] Received command: GetObjectCommand
-// [AWS Mock Debug] Found 1 mock(s) for GetObjectCommand
-// [AWS Mock Debug] Using mock at index 0 for GetObjectCommand
+// Interaction logs appear when commands are sent:
+// [aws-sdk-vitest-mock](Debug) Received command: GetObjectCommand
+// {
+//   "Bucket": "test-bucket",
+//   "Key": "file.txt"
+// }
+// [aws-sdk-vitest-mock](Debug) Found 1 mock(s) for GetObjectCommand
+// [aws-sdk-vitest-mock](Debug) Using mock at index 0 for GetObjectCommand
 await client.send(
   new GetObjectCommand({ Bucket: "test-bucket", Key: "file.txt" }),
 );
 
+// Lifecycle logs:
+// [aws-sdk-vitest-mock](Debug) Clearing call history (mocks preserved)
+s3Mock.reset();
+
+// [aws-sdk-vitest-mock](Debug) Restoring original client behavior and clearing all mocks
+s3Mock.restore();
+
 // Disable debug logging
 s3Mock.disableDebug();
 ```
 
-Debug mode logs include:
+Debug mode provides comprehensive logging for:
+
+**Mock Configuration:**
+
+- Mock setup with `.on()`, `.resolves()`, `.rejects()`, `.callsFake()`, etc.
+- Matcher details and strict mode settings
+- Paginated response configuration
+- File-based fixture loading
+
+**Mock Interactions:**
 
 - Incoming commands and their inputs
 - Number of configured mocks for each command
 - Mock matching results and reasons for failures
 - One-time mock removal notifications
 
+**Lifecycle Events:**
+
+- Reset operations (clearing call history)
+- Restore operations (removing all mocks)
+
 ## 🧪 Test Coverage
 
 The library includes comprehensive test suites covering all features:
@@ -480,7 +665,7 @@ Mocks an existing AWS SDK client instance.
 ### `AwsClientStub` Methods
 
 - `on(Command, matcher?, options?)` - Configure mock for a command
-- `reset()` - Clear all mocks and call history
+- `reset()` - Clear call history while preserving mock configurations
 - `restore()` - Restore original client behavior
 - `calls()` - Get call history
 - `enableDebug()` - Enable debug logging for troubleshooting
@@ -543,9 +728,11 @@ bun nx build
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for the complete guide.
 
-## 🙏 Acknowledgements
+## Acknowledgements
+
+This library is based on the core ideas and API patterns introduced by [aws-sdk-client-mock](https://github.com/m-radzikowski/aws-sdk-client-mock), which is no longer actively maintained.
 
-This library was inspired by [aws-sdk-client-mock](https://github.com/m-radzikowski/aws-sdk-client-mock). Adapted the core concepts and API design for Vitest while adding additional features and capabilities.
+It reimagines those concepts for Vitest, while extending them with additional features, improved ergonomics, and ongoing maintenance.
 
 ## 📝 License
 

package/index.cjs

@@ -1 +1,18 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=require("vitest"),P=require("node:fs"),R=require("node:path"),N=require("node:stream"),C=require("./matchers-Rq18z2C7.cjs");class d extends Error{constructor(e,o,c,n){super(e),this.name="AwsError",this.code=o,this.statusCode=c,this.retryable=n}}const W=t=>{const e=t?`The specified key does not exist. Key: ${t}`:"The specified key does not exist.";return new d(e,"NoSuchKey",404,!1)},M=t=>{const e=t?`The specified bucket does not exist. Bucket: ${t}`:"The specified bucket does not exist.";return new d(e,"NoSuchBucket",404,!1)},$=t=>{const e=t?`Access Denied for resource: ${t}`:"Access Denied";return new d(e,"AccessDenied",403,!1)},D=t=>{const e=t?`Requested resource not found: ${t}`:"Requested resource not found";return new d(e,"ResourceNotFoundException",400,!1)},I=()=>new d("The conditional request failed","ConditionalCheckFailedException",400,!1),O=()=>new d("Rate exceeded","Throttling",400,!0),T=()=>new d("We encountered an internal error. Please try again.","InternalServerError",500,!0);function k(){return{enabled:!1,log(t,e){this.enabled&&(e===void 0?console.log(`[aws-sdk-vitest-mock](Debug) ${t}`):console.log(`[aws-sdk-vitest-mock](Debug) ${t}`,e))}}}function y(t){t.enabled=!0}function v(t){t.enabled=!1}function F(t){const e=R.resolve(t),o=P.readFileSync(e,"utf8");return t.endsWith(".json")?JSON.parse(o):o}function L(t,e={}){const{pageSize:o=10,tokenKey:c="NextToken",itemsKey:n="Items"}=e;if(t.length===0)return[{[n]:[]}];const s=[];for(let r=0;r<t.length;r+=o){const u=t.slice(r,r+o),i=r+o<t.length,l={[n]:u};if(i){const a=l;a[c]=`token-${r+o}`}s.push(l)}return s}function A(){return typeof process<"u"&&process.versions?.node?"node":typeof process<"u"&&process.versions?.bun?"bun":"browser"}function K(t){const e=typeof t=="string"?Buffer.from(t,"utf8"):Buffer.from(t);let o=!1;return new N.Readable({read(){o||(this.push(e),this.push(null),o=!0)}})}function q(t){let e;return typeof t=="string"?e=new TextEncoder().encode(t):t instanceof Buffer?e=new Uint8Array(t):e=t,new ReadableStream({start(o){o.enqueue(e),o.close()}})}function h(t){const e=A();return e==="node"||e==="bun"?K(t):q(t)}function w(t,e){return Object.keys(e).every(o=>{const c=e[o],n=t[o];return c&&typeof c=="object"&&!Array.isArray(c)?typeof n!="object"||n===null?!1:w(n,c):n===c})}function j(t,e){if(t===e)return!0;if(typeof t!="object"||t===null||typeof e!="object"||e===null)return t===e;const o=Object.keys(t),c=Object.keys(e);return o.length!==c.length?!1:c.every(n=>{if(!Object.prototype.hasOwnProperty.call(t,n))return!1;const s=t,r=e,u=s[n],i=r[n];return typeof u=="object"&&u!==null&&typeof i=="object"&&i!==null?j(u,i):u===i})}function S(t){return async function(e){const o=()=>this;t.debugLogger.log(`Received command: ${e.constructor.name}`,e.input);const c=t.map.get(e.constructor);if(c){t.debugLogger.log(`Found ${c.length} mock(s) for ${e.constructor.name}`);const n=c.findIndex(s=>s.strict?s.matcher&&j(e.input,s.matcher):!s.matcher||w(e.input,s.matcher));if(n===-1)t.debugLogger.log(`No matching mock found for ${e.constructor.name}`,e.input);else{const s=c[n];if(!s)throw new Error(`Mock at index ${n} not found`);return t.debugLogger.log(`Using mock at index ${n} for ${e.constructor.name}`),s.once&&(c.splice(n,1),t.debugLogger.log(`Removed one-time mock for ${e.constructor.name}`)),s.handler(e.input,o())}}else t.debugLogger.log(`No mocks configured for ${e.constructor.name}`);throw new Error(`No mock configured for command: ${e.constructor.name}`)}}function x(t,e,o,c={}){const n=(r,u)=>{const i={matcher:o,handler:r,once:u,strict:!!c.strict},l=t.map.get(e)??[];if(u){const a=l.findIndex(f=>!f.once);a===-1?l.push(i):l.splice(a,0,i),t.map.set(e,l)}else{const a=l.filter(f=>f.once||JSON.stringify(f.matcher)!==JSON.stringify(o));a.push(i),t.map.set(e,a)}},s={resolves(r){return n(()=>Promise.resolve(r),!1),s},rejects(r){return n(()=>{const u=typeof r=="string"?new Error(r):r;return Promise.reject(u)},!1),s},callsFake(r){return n(r,!1),s},resolvesOnce(r){return n(()=>Promise.resolve(r),!0),s},rejectsOnce(r){return n(()=>{const u=typeof r=="string"?new Error(r):r;return Promise.reject(u)},!0),s},callsFakeOnce(r){return n(r,!0),s},resolvesStream(r){return n(()=>Promise.resolve({Body:h(r)}),!1),s},resolvesStreamOnce(r){return n(()=>Promise.resolve({Body:h(r)}),!0),s},resolvesWithDelay(r,u){const i=l=>{setTimeout(()=>l(r),u)};return n(()=>new Promise(i),!1),s},rejectsWithDelay(r,u){const i=typeof r=="string"?new Error(r):r,l=(a,f)=>{setTimeout(()=>f(i),u)};return n(()=>new Promise(l),!1),s},rejectsWithNoSuchKey(r){return n(()=>Promise.reject(W(r)),!1),s},rejectsWithNoSuchBucket(r){return n(()=>Promise.reject(M(r)),!1),s},rejectsWithAccessDenied(r){return n(()=>Promise.reject($(r)),!1),s},rejectsWithResourceNotFound(r){return n(()=>Promise.reject(D(r)),!1),s},rejectsWithConditionalCheckFailed(){return n(()=>Promise.reject(I()),!1),s},rejectsWithThrottling(){return n(()=>Promise.reject(O()),!1),s},rejectsWithInternalServerError(){return n(()=>Promise.reject(T()),!1),s},resolvesPaginated(r,u={}){const i=L(r,u);let l=0;return n(a=>{const f=u.tokenKey||"NextToken",p=a[f];if(p){const g=/token-(\d+)/.exec(p);if(g&&g[1]){const E=g[1];l=Math.floor(Number.parseInt(E,10)/(u.pageSize||10))}}else l=0;const m=i[l]||i[i.length-1]||i[0];if(!m)throw new Error("No paginated responses available");return l=Math.min(l+1,i.length-1),Promise.resolve(m)},!1),s},resolvesFromFile(r){return n(()=>{const u=F(r);return Promise.resolve(u)},!1),s}};return s}const B=t=>{const e={map:new WeakMap,debugLogger:k()},o=t.prototype,c=b.vi.spyOn(o,"send").mockImplementation(S(e));return{client:void 0,on:(s,r,u)=>x(e,s,r,u),reset:()=>{c.mockClear(),e.map=new WeakMap},restore:()=>{c.mockRestore(),e.map=new WeakMap},calls:()=>c.mock.calls.map(s=>s[0]),__rawCalls:()=>c.mock.calls,enableDebug:()=>{y(e.debugLogger)},disableDebug:()=>{v(e.debugLogger)}}},_=t=>{const e={map:new WeakMap,debugLogger:k()},o=b.vi.spyOn(t,"send").mockImplementation(S(e));return{client:t,on:(n,s,r)=>x(e,n,s,r),reset:()=>{o.mockClear(),e.map=new WeakMap},restore:()=>{o.mockRestore(),e.map=new WeakMap},calls:()=>o.mock.calls.map(n=>n[0]),__rawCalls:()=>o.mock.calls,enableDebug:()=>{y(e.debugLogger)},disableDebug:()=>{v(e.debugLogger)}}};exports.matchers=C.matchers;exports.mockClient=B;exports.mockClientInstance=_;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const v=require("vitest"),m=require("./matchers-Dkkl4vtx.cjs"),x=require("node:fs"),O=require("node:path"),F=require("node:stream");class f extends Error{constructor(t,o,i,n){super(t),this.name="AwsError",this.code=o,this.statusCode=i,this.retryable=n}}const L=e=>{const t=e?`The specified key does not exist. Key: ${e}`:"The specified key does not exist.";return new f(t,"NoSuchKey",404,!1)},D=e=>{const t=e?`The specified bucket does not exist. Bucket: ${e}`:"The specified bucket does not exist.";return new f(t,"NoSuchBucket",404,!1)},I=e=>{const t=e?`Access Denied for resource: ${e}`:"Access Denied";return new f(t,"AccessDenied",403,!1)},T=e=>{const t=e?`Requested resource not found: ${e}`:"Requested resource not found";return new f(t,"ResourceNotFoundException",400,!1)},K=()=>new f("The conditional request failed","ConditionalCheckFailedException",400,!1),M=()=>new f("Rate exceeded","Throttling",400,!0),A=()=>new f("We encountered an internal error. Please try again.","InternalServerError",500,!0);function B(e){try{return JSON.stringify(e,void 0,2)}catch{return typeof e=="object"&&e!==null?"[Complex Object]":typeof e=="string"?e:typeof e=="number"||typeof e=="boolean"?String(e):"[Non-serializable value]"}}function j(){return{enabled:!1,log(e,t){if(this.enabled)if(t===void 0)console.log(`${m.colors.magenta("aws-sdk-vitest-mock(debug):")} ${e}`);else{const o=B(t);console.log(`${m.colors.magenta("aws-sdk-vitest-mock(debug):")} ${e}
+${o}`)}}}}function S(e){e.enabled=!0}function w(e){e.enabled=!1}function q(e){const t=O.resolve(e),o=x.readFileSync(t,"utf8");return e.endsWith(".json")?JSON.parse(o):o}function J(e,t={}){const{pageSize:o=10,tokenKey:i="NextToken",itemsKey:n="Items"}=t;if(e.length===0)return[{[n]:[]}];const s=[];for(let r=0;r<e.length;r+=o){const c=e.slice(r,r+o),u=r+o<e.length,l={[n]:c};if(u){const g=l,a=c[c.length-1];g[i]=a}s.push(l)}return s}function _(){return typeof process<"u"&&process.versions?.node?"node":typeof process<"u"&&process.versions?.bun?"bun":"browser"}function z(e){const t=typeof e=="string"?Buffer.from(e,"utf8"):Buffer.from(e);let o=!1;return new F.Readable({read(){o||(this.push(t),this.push(null),o=!0)}})}function V(e){let t;return typeof e=="string"?t=new TextEncoder().encode(e):e instanceof Buffer?t=new Uint8Array(e):t=e,new ReadableStream({start(o){o.enqueue(t),o.close()}})}function k(e){const t=_();return t==="node"||t==="bun"?z(e):V(e)}function $(e,t){return Object.keys(t).every(o=>{const i=t[o],n=e[o];return i&&typeof i=="object"&&!Array.isArray(i)?typeof n!="object"||n===null?!1:$(n,i):n===i})}function C(e,t){if(e===t)return!0;if(typeof e!="object"||e===null||typeof t!="object"||t===null)return e===t;const o=Object.keys(e),i=Object.keys(t);return o.length!==i.length?!1:i.every(n=>{if(!Object.prototype.hasOwnProperty.call(e,n))return!1;const s=e,r=t,c=s[n],u=r[n];return typeof c=="object"&&c!==null&&typeof u=="object"&&u!==null?C(c,u):c===u})}function N(e){return async function(t){const o=()=>this;e.debugLogger.log(`Received command: ${t.constructor.name}`,t.input);const i=e.map.get(t.constructor);if(i){e.debugLogger.log(`Found ${i.length} mock(s) for ${t.constructor.name}`);const s=i.findIndex(r=>r.strict?r.matcher&&C(t.input,r.matcher):!r.matcher||$(t.input,r.matcher));if(s===-1){e.debugLogger.log(`No matching mock found for ${t.constructor.name}`,t.input);const r=i.map((u,l)=>{const g=u.matcher?JSON.stringify(u.matcher,void 0,2):"any input",a=u.strict?" (strict mode)":"";return`  Mock #${l+1}: ${g}${a}`}).join(`
+`),c=JSON.stringify(t.input,void 0,2);throw new Error(`No matching mock found for ${t.constructor.name}.
+
+Found ${i.length} mock(s) but none matched the input.
+
+Configured mocks:
+${r}
+
+Received input:
+${c}
+
+Tip: Enable debug mode with enableDebug() for detailed matching information.`)}else{const r=i[s];if(!r)throw new Error(`Mock at index ${s} not found`);return e.debugLogger.log(`Using mock at index ${s} for ${t.constructor.name}`),r.once&&(i.splice(s,1),e.debugLogger.log(`Removed one-time mock for ${t.constructor.name}`)),r.handler(t.input,o())}}else e.debugLogger.log(`No mocks configured for ${t.constructor.name}`);const n=JSON.stringify(t.input,void 0,2);throw new Error(`No mock configured for command: ${t.constructor.name}.
+
+Received input:
+${n}
+
+Did you forget to call mockClient.on(${t.constructor.name})?`)}}function R(e,t,o,i={}){const n=(r,c,u)=>{const l={matcher:o,handler:r,once:c,strict:!!i.strict},g=e.map.get(t)??[];if(c){const a=g.findIndex(d=>!d.once);a===-1?g.push(l):g.splice(a,0,l),e.map.set(t,g),e.debugLogger.log(`Configured ${u}Once for ${t.name}`,o?{matcher:o,strict:!!i.strict}:void 0)}else{const a=g.filter(d=>d.once||JSON.stringify(d.matcher)!==JSON.stringify(o));a.push(l),e.map.set(t,a),e.debugLogger.log(`Configured ${u} for ${t.name}`,o?{matcher:o,strict:!!i.strict}:void 0)}},s={resolves(r){return n(()=>Promise.resolve(r),!1,"resolves"),s},rejects(r){return n(()=>{const c=typeof r=="string"?new Error(r):r;return Promise.reject(c)},!1,"rejects"),s},callsFake(r){return n(r,!1,"callsFake"),s},resolvesOnce(r){return n(()=>Promise.resolve(r),!0,"resolves"),s},rejectsOnce(r){return n(()=>{const c=typeof r=="string"?new Error(r):r;return Promise.reject(c)},!0,"rejects"),s},callsFakeOnce(r){return n(r,!0,"callsFake"),s},resolvesStream(r){return n(()=>Promise.resolve({Body:k(r)}),!1,"resolvesStream"),s},resolvesStreamOnce(r){return n(()=>Promise.resolve({Body:k(r)}),!0,"resolvesStream"),s},resolvesWithDelay(r,c){const u=l=>{setTimeout(()=>l(r),c)};return n(()=>new Promise(u),!1,"resolvesWithDelay"),s},rejectsWithDelay(r,c){const u=typeof r=="string"?new Error(r):r,l=(g,a)=>{setTimeout(()=>a(u),c)};return n(()=>new Promise(l),!1,"rejectsWithDelay"),s},rejectsWithNoSuchKey(r){return n(()=>Promise.reject(L(r)),!1,"rejectsWithNoSuchKey"),s},rejectsWithNoSuchBucket(r){return n(()=>Promise.reject(D(r)),!1,"rejectsWithNoSuchBucket"),s},rejectsWithAccessDenied(r){return n(()=>Promise.reject(I(r)),!1,"rejectsWithAccessDenied"),s},rejectsWithResourceNotFound(r){return n(()=>Promise.reject(T(r)),!1,"rejectsWithResourceNotFound"),s},rejectsWithConditionalCheckFailed(){return n(()=>Promise.reject(K()),!1,"rejectsWithConditionalCheckFailed"),s},rejectsWithThrottling(){return n(()=>Promise.reject(M()),!1,"rejectsWithThrottling"),s},rejectsWithInternalServerError(){return n(()=>Promise.reject(A()),!1,"rejectsWithInternalServerError"),s},resolvesPaginated(r,c={}){const u=J(r,c);let l=0;return e.debugLogger.log(`Configured resolvesPaginated for ${t.name}`,{pageSize:c.pageSize,itemsCount:r.length}),n(g=>{const a=c.tokenKey||"NextToken",d=c.inputTokenKey||a,h=g[d];if(h!=null){const E=c.itemsKey||"Items";let y=0;for(const W of u){const p=W[E];if(p&&p.length>0){const P=p[p.length-1];if(JSON.stringify(P)===JSON.stringify(h)){l=y+1;break}}y++}}else l=0;const b=u[l]||u[u.length-1]||u[0];if(!b)throw new Error("No paginated responses available");return l=Math.min(l+1,u.length-1),Promise.resolve(b)},!1,"resolvesPaginated"),s},resolvesFromFile(r){return e.debugLogger.log(`Configured resolvesFromFile for ${t.name}`,{filePath:r}),n(()=>{const c=q(r);return Promise.resolve(c)},!1,"resolvesFromFile"),s}};return s}const U=e=>{const t={map:new WeakMap,debugLogger:j()},o=e.prototype,i=v.vi.spyOn(o,"send").mockImplementation(N(t));return{client:void 0,on:(s,r,c)=>R(t,s,r,c),reset:()=>{t.debugLogger.log("Clearing call history (mocks preserved)"),i.mockClear()},restore:()=>{t.debugLogger.log("Restoring original client behavior and clearing all mocks"),i.mockRestore(),t.map=new WeakMap},calls:()=>i.mock.calls.map(s=>s[0]),__rawCalls:()=>i.mock.calls,enableDebug:()=>{S(t.debugLogger)},disableDebug:()=>{w(t.debugLogger)}}},G=e=>{const t={map:new WeakMap,debugLogger:j()},o=v.vi.spyOn(e,"send").mockImplementation(N(t));return{client:e,on:(n,s,r)=>R(t,n,s,r),reset:()=>{t.debugLogger.log("Clearing call history (mocks preserved) for client instance"),o.mockClear()},restore:()=>{t.debugLogger.log("Restoring original client behavior and clearing all mocks for client instance"),o.mockRestore(),t.map=new WeakMap},calls:()=>o.mock.calls.map(n=>n[0]),__rawCalls:()=>o.mock.calls,enableDebug:()=>{S(t.debugLogger)},disableDebug:()=>{w(t.debugLogger)}}};exports.matchers=m.matchers;exports.mockClient=U;exports.mockClientInstance=G;

package/index.d.ts

@@ -1,2 +1,47 @@
-export * from './lib/mock-client.js';
+/**
+ * AWS SDK Vitest Mock - A powerful, type-safe mocking library for AWS SDK v3 with Vitest
+ *
+ * @packageDocumentation
+ *
+ * @example Basic Setup
+ * ```typescript
+ * import { mockClient } from 'aws-sdk-vitest-mock';
+ * import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+ *
+ * const s3Mock = mockClient(S3Client);
+ * s3Mock.on(GetObjectCommand).resolves({ Body: 'file contents' });
+ *
+ * const client = new S3Client({});
+ * const result = await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file.txt' }));
+ * ```
+ *
+ * @example Using Matchers
+ * ```typescript
+ * import { expect } from 'vitest';
+ * import { matchers } from 'aws-sdk-vitest-mock';
+ *
+ * expect.extend(matchers);
+ *
+ * expect(s3Mock).toHaveReceivedCommand(GetObjectCommand);
+ * ```
+ */
+/**
+ * Core Functions for mocking AWS SDK clients
+ * @category Core Functions
+ */
+export { mockClient, mockClientInstance } from './lib/mock-client.js';
+/**
+ * Command stub interface for configuring mock behaviors
+ * @category Command Stub
+ */
+export type { AwsCommandStub, AwsClientStub } from './lib/mock-client.js';
+/**
+ * Custom Vitest matchers for AWS SDK assertions
+ * @category Matchers
+ */
 export { matchers } from './lib/matchers.js';
+/**
+ * TypeScript types for matcher interfaces
+ * @category Matchers
+ */
+export type { AwsSdkMatchers } from './lib/matchers.js';