aws-sdk-vitest-mock 0.4.0 → 0.6.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';
 
-dynamoMock.on(ScanCommand).resolvesPaginated(items, {
-  pageSize: 10,
+// 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", // 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", ... }));
 
-// Second call with ExclusiveStartKey returns items 11-20
-const result2 = await client.send(
+// 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: "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
+```
 
-// 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) => ({
+#### 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: 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,102 @@ 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:
+#### Global Debug Configuration
+
+Enable debug logging for all mocks globally, with the ability to override at the individual mock level:
+
+```typescript
+import { setGlobalDebug, mockClient } from "aws-sdk-vitest-mock";
+import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
+import { DynamoDBClient, GetItemCommand } from "@aws-sdk/client-dynamodb";
+
+// Enable debug for all mocks
+setGlobalDebug(true);
+
+// All mocks will inherit the global debug setting
+const s3Mock = mockClient(S3Client);
+const dynamoMock = mockClient(DynamoDBClient);
+
+// Both mocks will log debug information
+s3Mock.on(GetObjectCommand).resolves({ Body: "data" });
+dynamoMock.on(GetItemCommand).resolves({ Item: { id: { S: "1" } } });
+
+// Override global setting for a specific mock
+s3Mock.disableDebug(); // This mock won't log, but dynamoMock still will
+
+// Disable global debug
+setGlobalDebug(false);
+```
+
+**Debug Priority (highest to lowest):**
+
+1. Individual mock's `enableDebug()` or `disableDebug()` call (explicit override)
+2. Global debug setting via `setGlobalDebug()`
+3. Default: disabled
+
+**Key behaviors:**
+
+- When global debug is enabled, all new and existing mocks will log unless explicitly disabled
+- Individual mock settings always take priority over global settings
+- `reset()` preserves individual debug settings
+- Global debug can be changed at any time and affects all mocks without explicit settings
+
+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:
@@ -513,6 +690,8 @@ test("should call DynamoDB", async () => {
 
 ## 📚 API Reference
 
+> TypeScript documentation for this library can be found at [here](https://sudokar.github.io/aws-sdk-vitest-mock/)
+
 ### `mockClient<TClient>(ClientConstructor)`
 
 Creates a mock for an AWS SDK client constructor.
@@ -525,14 +704,18 @@ Mocks an existing AWS SDK client instance.
 
 **Returns:** `AwsClientStub<TClient>`
 
+### Global Debug Functions
+
+- `setGlobalDebug(enabled: boolean)` - Enable or disable debug logging globally for all mocks
+
 ### `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
-- `disableDebug()` - Disable debug logging
+- `enableDebug()` - Enable debug logging for troubleshooting (overrides global setting)
+- `disableDebug()` - Disable debug logging (overrides global setting)
 
 ### `AwsCommandStub` Methods (Chainable)
 

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 j=require("vitest"),D=require("./matchers-CNhdB_9q.cjs"),F=require("node:fs"),I=require("node:path"),M=require("node:stream");class d extends Error{constructor(t,o,i,n){super(t),this.name="AwsError",this.code=o,this.statusCode=i,this.retryable=n}}const T=e=>new d(e?`The specified key does not exist. Key: ${e}`:"The specified key does not exist.","NoSuchKey",404,!1),K=e=>new d(e?`The specified bucket does not exist. Bucket: ${e}`:"The specified bucket does not exist.","NoSuchBucket",404,!1),A=e=>new d(e?`Access Denied for resource: ${e}`:"Access Denied","AccessDenied",403,!1),B=e=>new d(e?`Requested resource not found: ${e}`:"Requested resource not found","ResourceNotFoundException",400,!1),q=()=>new d("The conditional request failed","ConditionalCheckFailedException",400,!1),J=()=>new d("Rate exceeded","Throttling",400,!0),_=()=>new d("We encountered an internal error. Please try again.","InternalServerError",500,!0),z=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]"}},v=(e,t)=>{const o=D.colors.magenta("aws-sdk-vitest-mock(debug):");if(t===void 0)console.log(`${o} ${e}`);else{const i=z(t);console.log(`${o} ${e}
+${i}`)}},L=(e=!1)=>({enabled:e,explicitlySet:!1,log(t,o){this.enabled&&v(t,o)},logDirect(t,o){v(t,o)}}),w=e=>{e.enabled=!0,e.explicitlySet=!0},$=e=>{e.enabled=!1,e.explicitlySet=!0},V=e=>{const t=I.resolve(e),o=F.readFileSync(t,"utf8");return e.endsWith(".json")?JSON.parse(o):o},G=(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),l=r+o<e.length,u={[n]:c};if(l){const a=u,g=c[c.length-1];a[i]=g}s.push(u)}return s},U=()=>typeof process<"u"&&process.versions?.node?"node":typeof process<"u"&&process.versions?.bun?"bun":"browser",H=e=>{const t=typeof e=="string"?Buffer.from(e,"utf8"):Buffer.from(e);let o=!1;return new M.Readable({read(){o||(this.push(t),this.push(null),o=!0)}})},Q=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()}})},S=e=>{const t=U();return t==="node"||t==="bun"?H(e):Q(e)};let N=!1;function X(e){N=e}function h(e){return e.explicitlySet?e.enabled:N}function C(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:C(n,i):n===i})}function E(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],l=r[n];return typeof c=="object"&&c!==null&&typeof l=="object"&&l!==null?E(c,l):c===l})}function Y(e,t,o){const i=t.map((s,r)=>{const c=s.matcher?JSON.stringify(s.matcher,void 0,2):"any input",l=s.strict?" (strict mode)":"";return`  Mock #${r+1}: ${c}${l}`}).join(`
+`),n=JSON.stringify(o,void 0,2);return new Error(`No matching mock found for ${e}.
+
+Found ${t.length} mock(s) but none matched the input.
+
+Configured mocks:
+${i}
+
+Received input:
+${n}
+
+Tip: Enable debug mode with enableDebug() for detailed matching information.`)}function Z(e,t){const o=JSON.stringify(t,void 0,2);return new Error(`No mock configured for command: ${e}.
+
+Received input:
+${o}
+
+Did you forget to call mockClient.on(${e})?`)}function ee(e,t){return e.findIndex(o=>o.strict?o.matcher&&E(t,o.matcher):!o.matcher||C(t,o.matcher))}function x(e){return async function(t){const o=()=>this,i=h(e.debugLogger),n=t.constructor.name;i&&e.debugLogger.logDirect(`Received command: ${n}`,t.input);const s=e.map.get(t.constructor);if(!s)throw i&&e.debugLogger.logDirect(`No mocks configured for ${n}`),Z(n,t.input);i&&e.debugLogger.logDirect(`Found ${s.length} mock(s) for ${n}`);const r=ee(s,t.input);if(r===-1)throw i&&e.debugLogger.logDirect(`No matching mock found for ${n}`,t.input),Y(n,s,t.input);const c=s[r];if(!c)throw new Error(`Mock at index ${r} not found`);return i&&e.debugLogger.logDirect(`Using mock at index ${r} for ${n}`),c.once&&(s.splice(r,1),i&&e.debugLogger.logDirect(`Removed one-time mock for ${n}`)),c.handler(t.input,o())}}function R(e,t,o,i={}){const n=(r,c,l)=>{const u={matcher:o,handler:r,once:c,strict:!!i.strict},a=e.map.get(t)??[],g=h(e.debugLogger);if(c){const f=a.findIndex(p=>!p.once);f===-1?a.push(u):a.splice(f,0,u),e.map.set(t,a),g&&e.debugLogger.logDirect(`Configured ${l}Once for ${t.name}`,o?{matcher:o,strict:!!i.strict}:void 0)}else{const f=a.filter(p=>p.once||JSON.stringify(p.matcher)!==JSON.stringify(o));f.push(u),e.map.set(t,f),g&&e.debugLogger.logDirect(`Configured ${l} 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:S(r)}),!1,"resolvesStream"),s},resolvesStreamOnce(r){return n(()=>Promise.resolve({Body:S(r)}),!0,"resolvesStream"),s},resolvesWithDelay(r,c){const l=u=>{setTimeout(()=>u(r),c)};return n(()=>new Promise(l),!1,"resolvesWithDelay"),s},rejectsWithDelay(r,c){const l=typeof r=="string"?new Error(r):r,u=(a,g)=>{setTimeout(()=>g(l),c)};return n(()=>new Promise(u),!1,"rejectsWithDelay"),s},rejectsWithNoSuchKey(r){return n(()=>Promise.reject(T(r)),!1,"rejectsWithNoSuchKey"),s},rejectsWithNoSuchBucket(r){return n(()=>Promise.reject(K(r)),!1,"rejectsWithNoSuchBucket"),s},rejectsWithAccessDenied(r){return n(()=>Promise.reject(A(r)),!1,"rejectsWithAccessDenied"),s},rejectsWithResourceNotFound(r){return n(()=>Promise.reject(B(r)),!1,"rejectsWithResourceNotFound"),s},rejectsWithConditionalCheckFailed(){return n(()=>Promise.reject(q()),!1,"rejectsWithConditionalCheckFailed"),s},rejectsWithThrottling(){return n(()=>Promise.reject(J()),!1,"rejectsWithThrottling"),s},rejectsWithInternalServerError(){return n(()=>Promise.reject(_()),!1,"rejectsWithInternalServerError"),s},resolvesPaginated(r,c={}){const l=G(r,c);let u=0;return e.debugLogger.log(`Configured resolvesPaginated for ${t.name}`,{pageSize:c.pageSize,itemsCount:r.length}),n(a=>{const g=c.tokenKey||"NextToken",f=c.inputTokenKey||g,m=a[f];if(m!=null){const W=c.itemsKey||"Items";let k=0;for(const P of l){const b=P[W];if(b&&b.length>0){const O=b[b.length-1];if(JSON.stringify(O)===JSON.stringify(m)){u=k+1;break}}k++}}else u=0;const y=l[u]||l[l.length-1]||l[0];if(!y)throw new Error("No paginated responses available");return u=Math.min(u+1,l.length-1),Promise.resolve(y)},!1,"resolvesPaginated"),s},resolvesFromFile(r){return e.debugLogger.log(`Configured resolvesFromFile for ${t.name}`,{filePath:r}),n(()=>{const c=V(r);return Promise.resolve(c)},!1,"resolvesFromFile"),s}};return s}const te=e=>{const t={map:new WeakMap,debugLogger:L()},o=e.prototype,i=j.vi.spyOn(o,"send").mockImplementation(x(t));return{client:void 0,on:(s,r,c)=>R(t,s,r,c),reset:()=>{h(t.debugLogger)&&t.debugLogger.logDirect("Clearing call history (mocks preserved)"),i.mockClear()},restore:()=>{h(t.debugLogger)&&t.debugLogger.logDirect("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:()=>{w(t.debugLogger)},disableDebug:()=>{$(t.debugLogger)}}},re=e=>{const t={map:new WeakMap,debugLogger:L()},o=j.vi.spyOn(e,"send").mockImplementation(x(t));return{client:e,on:(n,s,r)=>R(t,n,s,r),reset:()=>{h(t.debugLogger)&&t.debugLogger.logDirect("Clearing call history (mocks preserved) for client instance"),o.mockClear()},restore:()=>{h(t.debugLogger)&&t.debugLogger.logDirect("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:()=>{w(t.debugLogger)},disableDebug:()=>{$(t.debugLogger)}}};exports.matchers=D.matchers;exports.mockClient=te;exports.mockClientInstance=re;exports.setGlobalDebug=X;

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, setGlobalDebug, } 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';