aws-sdk-vitest-mock 0.4.0 → 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
@@ -104,6 +122,9 @@ Understanding these concepts will help you use the library effectively:
 - **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
 
@@ -190,6 +211,39 @@ test("should mock existing S3 client instance", async () => {
 });
 ```
 
+### Test Lifecycle Management
+
+Use `reset()` to clear call history between assertions while keeping mock configurations. Use `restore()` to completely clean up mocking:
+
+```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
@@ -311,55 +365,94 @@ s3Mock
 
 ### Paginator Support
 
-Mock AWS SDK v3 pagination with automatic token handling:
+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
-// Mock DynamoDB scan with pagination
-// DynamoDB uses different keys for input (ExclusiveStartKey) and output (LastEvaluatedKey)
-const items = Array.from({ length: 25 }, (_, i) => ({
-  id: { S: `item-${i + 1}` },
-}));
+import { marshall, unmarshall } from '@aws-sdk/util-dynamodb';
+import { DynamoDBClient, ScanCommand } from '@aws-sdk/client-dynamodb';
+
+// 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" },
+];
 
-dynamoMock.on(ScanCommand).resolvesPaginated(items, {
-  pageSize: 10,
+const marshalledUsers = users.map(user => marshall(user));
+
+// Configure pagination
+dynamoMock.on(ScanCommand).resolvesPaginated(marshalledUsers, {
+  pageSize: 1,
   itemsKey: "Items",
-  tokenKey: "LastEvaluatedKey", // Token key in response
-  inputTokenKey: "ExclusiveStartKey", // Token key in request (when different from response)
+  tokenKey: "LastEvaluatedKey",      // DynamoDB response key
+  inputTokenKey: "ExclusiveStartKey"  // DynamoDB request key
 });
 
-// First call returns items 1-10 with LastEvaluatedKey
-const result1 = await client.send(new ScanCommand({ TableName: "test" }));
-// result1.LastEvaluatedKey = "token-10"
+// 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", ... }
 
-// Second call with ExclusiveStartKey returns items 11-20
-const result2 = await client.send(
+// Page 2: Use LastEvaluatedKey to get next page
+const page2 = await client.send(
   new ScanCommand({
-    TableName: "test",
-    ExclusiveStartKey: result1.LastEvaluatedKey,
-  }),
+    TableName: "Users",
+    ExclusiveStartKey: page1.LastEvaluatedKey, // Pass the object directly
+  })
 );
-// result2.LastEvaluatedKey = "token-20"
 
-// Third call returns items 21-25 without LastEvaluatedKey
-const result3 = await client.send(
+// Page 3: Continue until LastEvaluatedKey is undefined
+const page3 = await client.send(
   new ScanCommand({
-    TableName: "test",
-    ExclusiveStartKey: result2.LastEvaluatedKey,
-  }),
+    TableName: "Users",
+    ExclusiveStartKey: page2.LastEvaluatedKey,
+  })
 );
-// result3.LastEvaluatedKey = undefined (no more pages)
+expect(page3.LastEvaluatedKey).toBeUndefined(); // No more pages
+```
+
+#### S3 Pagination
+
+```typescript
+import { S3Client, ListObjectsV2Command } from '@aws-sdk/client-s3';
 
-// Mock S3 list objects with pagination
-// S3 uses the same key for input and output, so inputTokenKey is optional
-const objects = Array.from({ length: 15 }, (_, i) => ({
+const objects = Array.from({ length: 100 }, (_, i) => ({
   Key: `file-${i + 1}.txt`,
+  Size: 1024,
+  LastModified: new Date(),
 }));
 
 s3Mock.on(ListObjectsV2Command).resolvesPaginated(objects, {
-  pageSize: 10,
+  pageSize: 50,
   itemsKey: "Contents",
-  tokenKey: "NextContinuationToken", // Used for both input and output
+  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:**
@@ -367,7 +460,20 @@ s3Mock.on(ListObjectsV2Command).resolvesPaginated(objects, {
 - `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")
-- `inputTokenKey` - Property name for pagination token in request (default: same as `tokenKey`)
+  - 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
@@ -415,9 +521,7 @@ s3Mock.on(GetObjectCommand).resolvesFromFile("./fixtures/response.txt");
 
 ### Debug Mode
 
-Enable debug logging to troubleshoot mock configurations when they're not matching as expected:
-
-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);
@@ -425,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:
@@ -528,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

package/index.cjs

@@ -1 +1,18 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=require("vitest"),R=require("node:fs"),N=require("node:path"),C=require("node:stream"),W=require("./matchers-Rq18z2C7.cjs");class d extends Error{constructor(e,s,c,n){super(e),this.name="AwsError",this.code=s,this.statusCode=c,this.retryable=n}}const M=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)},T=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),F=()=>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 L(t){const e=N.resolve(t),s=R.readFileSync(e,"utf8");return t.endsWith(".json")?JSON.parse(s):s}function K(t,e={}){const{pageSize:s=10,tokenKey:c="NextToken",itemsKey:n="Items"}=e;if(t.length===0)return[{[n]:[]}];const o=[];for(let r=0;r<t.length;r+=s){const u=t.slice(r,r+s),i=r+s<t.length,l={[n]:u};if(i){const a=l;a[c]=`token-${r+s}`}o.push(l)}return o}function A(){return typeof process<"u"&&process.versions?.node?"node":typeof process<"u"&&process.versions?.bun?"bun":"browser"}function q(t){const e=typeof t=="string"?Buffer.from(t,"utf8"):Buffer.from(t);let s=!1;return new C.Readable({read(){s||(this.push(e),this.push(null),s=!0)}})}function B(t){let e;return typeof t=="string"?e=new TextEncoder().encode(t):t instanceof Buffer?e=new Uint8Array(t):e=t,new ReadableStream({start(s){s.enqueue(e),s.close()}})}function h(t){const e=A();return e==="node"||e==="bun"?q(t):B(t)}function w(t,e){return Object.keys(e).every(s=>{const c=e[s],n=t[s];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 s=Object.keys(t),c=Object.keys(e);return s.length!==c.length?!1:c.every(n=>{if(!Object.prototype.hasOwnProperty.call(t,n))return!1;const o=t,r=e,u=o[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 s=()=>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(o=>o.strict?o.matcher&&j(e.input,o.matcher):!o.matcher||w(e.input,o.matcher));if(n===-1)t.debugLogger.log(`No matching mock found for ${e.constructor.name}`,e.input);else{const o=c[n];if(!o)throw new Error(`Mock at index ${n} not found`);return t.debugLogger.log(`Using mock at index ${n} for ${e.constructor.name}`),o.once&&(c.splice(n,1),t.debugLogger.log(`Removed one-time mock for ${e.constructor.name}`)),o.handler(e.input,s())}}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,s,c={}){const n=(r,u)=>{const i={matcher:s,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(s));a.push(i),t.map.set(e,a)}},o={resolves(r){return n(()=>Promise.resolve(r),!1),o},rejects(r){return n(()=>{const u=typeof r=="string"?new Error(r):r;return Promise.reject(u)},!1),o},callsFake(r){return n(r,!1),o},resolvesOnce(r){return n(()=>Promise.resolve(r),!0),o},rejectsOnce(r){return n(()=>{const u=typeof r=="string"?new Error(r):r;return Promise.reject(u)},!0),o},callsFakeOnce(r){return n(r,!0),o},resolvesStream(r){return n(()=>Promise.resolve({Body:h(r)}),!1),o},resolvesStreamOnce(r){return n(()=>Promise.resolve({Body:h(r)}),!0),o},resolvesWithDelay(r,u){const i=l=>{setTimeout(()=>l(r),u)};return n(()=>new Promise(i),!1),o},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),o},rejectsWithNoSuchKey(r){return n(()=>Promise.reject(M(r)),!1),o},rejectsWithNoSuchBucket(r){return n(()=>Promise.reject(T(r)),!1),o},rejectsWithAccessDenied(r){return n(()=>Promise.reject($(r)),!1),o},rejectsWithResourceNotFound(r){return n(()=>Promise.reject(D(r)),!1),o},rejectsWithConditionalCheckFailed(){return n(()=>Promise.reject(I()),!1),o},rejectsWithThrottling(){return n(()=>Promise.reject(O()),!1),o},rejectsWithInternalServerError(){return n(()=>Promise.reject(F()),!1),o},resolvesPaginated(r,u={}){const i=K(r,u);let l=0;return n(a=>{const f=u.tokenKey||"NextToken",E=u.inputTokenKey||f,p=a[E];if(p){const g=/token-(\d+)/.exec(p);if(g&&g[1]){const P=g[1];l=Math.floor(Number.parseInt(P,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),o},resolvesFromFile(r){return n(()=>{const u=L(r);return Promise.resolve(u)},!1),o}};return o}const _=t=>{const e={map:new WeakMap,debugLogger:k()},s=t.prototype,c=b.vi.spyOn(s,"send").mockImplementation(S(e));return{client:void 0,on:(o,r,u)=>x(e,o,r,u),reset:()=>{c.mockClear(),e.map=new WeakMap},restore:()=>{c.mockRestore(),e.map=new WeakMap},calls:()=>c.mock.calls.map(o=>o[0]),__rawCalls:()=>c.mock.calls,enableDebug:()=>{y(e.debugLogger)},disableDebug:()=>{v(e.debugLogger)}}},V=t=>{const e={map:new WeakMap,debugLogger:k()},s=b.vi.spyOn(t,"send").mockImplementation(S(e));return{client:t,on:(n,o,r)=>x(e,n,o,r),reset:()=>{s.mockClear(),e.map=new WeakMap},restore:()=>{s.mockRestore(),e.map=new WeakMap},calls:()=>s.mock.calls.map(n=>n[0]),__rawCalls:()=>s.mock.calls,enableDebug:()=>{y(e.debugLogger)},disableDebug:()=>{v(e.debugLogger)}}};exports.matchers=W.matchers;exports.mockClient=_;exports.mockClientInstance=V;
+"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';