aws-sdk-vitest-mock 0.4.0 → 0.6.0

package/lib/matchers.d.ts

@@ -4,22 +4,163 @@ interface MatcherResult {
     pass: boolean;
     message: () => string;
 }
+/**
+ * Custom Vitest matchers for asserting AWS SDK command calls.
+ *
+ * @category Matchers
+ *
+ * @example Setup matchers in your test setup file
+ * ```typescript
+ * import { expect } from 'vitest';
+ * import { matchers } from 'aws-sdk-vitest-mock';
+ *
+ * expect.extend(matchers);
+ * ```
+ */
 export declare const matchers: {
+    /**
+     * Assert that a command was received at least once.
+     *
+     * @param received - The AWS client stub
+     * @param command - The command constructor to check for
+     * @returns Matcher result
+     *
+     * @example
+     * ```typescript
+     * const s3Mock = mockClient(S3Client);
+     * const client = new S3Client({});
+     *
+     * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file.txt' }));
+     *
+     * expect(s3Mock).toHaveReceivedCommand(GetObjectCommand);
+     * ```
+     */
     toHaveReceivedCommand<TInput extends object, TOutput extends MetadataBearer>(received: AwsClientStub, command: CommandConstructor<TInput, TOutput>): MatcherResult;
+    /**
+     * Assert that a command was received exactly N times.
+     *
+     * @param received - The AWS client stub
+     * @param command - The command constructor to check for
+     * @param times - The exact number of times the command should have been received
+     * @returns Matcher result
+     *
+     * @example
+     * ```typescript
+     * const s3Mock = mockClient(S3Client);
+     * const client = new S3Client({});
+     *
+     * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file1.txt' }));
+     * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file2.txt' }));
+     *
+     * expect(s3Mock).toHaveReceivedCommandTimes(GetObjectCommand, 2);
+     * ```
+     */
     toHaveReceivedCommandTimes<TInput extends object, TOutput extends MetadataBearer>(received: AwsClientStub, command: CommandConstructor<TInput, TOutput>, times: number): MatcherResult;
+    /**
+     * Assert that a command was received with specific input parameters.
+     *
+     * @param received - The AWS client stub
+     * @param command - The command constructor to check for
+     * @param input - The expected input parameters
+     * @returns Matcher result
+     *
+     * @example
+     * ```typescript
+     * const s3Mock = mockClient(S3Client);
+     * const client = new S3Client({});
+     *
+     * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file.txt' }));
+     *
+     * expect(s3Mock).toHaveReceivedCommandWith(GetObjectCommand, {
+     *   Bucket: 'test',
+     *   Key: 'file.txt'
+     * });
+     * ```
+     */
     toHaveReceivedCommandWith<TInput extends object, TOutput extends MetadataBearer>(this: {
         equals: (a: unknown, b: unknown) => boolean;
     }, received: AwsClientStub, command: CommandConstructor<TInput, TOutput>, input: TInput): MatcherResult;
+    /**
+     * Assert that the Nth command call was a specific command with specific input.
+     *
+     * @param received - The AWS client stub
+     * @param n - The call number (1-indexed)
+     * @param command - The command constructor to check for
+     * @param input - The expected input parameters
+     * @returns Matcher result
+     *
+     * @example
+     * ```typescript
+     * const s3Mock = mockClient(S3Client);
+     * const client = new S3Client({});
+     *
+     * await client.send(new PutObjectCommand({ Bucket: 'test', Key: 'file1.txt' }));
+     * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file2.txt' }));
+     *
+     * expect(s3Mock).toHaveReceivedNthCommandWith(2, GetObjectCommand, {
+     *   Bucket: 'test',
+     *   Key: 'file2.txt'
+     * });
+     * ```
+     */
     toHaveReceivedNthCommandWith<TInput extends object, TOutput extends MetadataBearer>(this: {
         equals: (a: unknown, b: unknown) => boolean;
     }, received: AwsClientStub, n: number, command: CommandConstructor<TInput, TOutput>, input: TInput): MatcherResult;
+    /**
+     * Assert that no commands other than the expected ones were received.
+     *
+     * @param received - The AWS client stub
+     * @param expectedCommands - Array of command constructors that are allowed
+     * @returns Matcher result
+     *
+     * @example
+     * ```typescript
+     * const s3Mock = mockClient(S3Client);
+     * const client = new S3Client({});
+     *
+     * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file.txt' }));
+     * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'other.txt' }));
+     *
+     * expect(s3Mock).toHaveReceivedNoOtherCommands([GetObjectCommand]);
+     * ```
+     */
     toHaveReceivedNoOtherCommands<TInput extends object, TOutput extends MetadataBearer>(received: AwsClientStub, expectedCommands?: CommandConstructor<TInput, TOutput>[]): MatcherResult;
 };
+/**
+ * TypeScript interface for AWS SDK Vitest matchers.
+ * This interface is used to extend Vitest's assertion types.
+ *
+ * @category Matchers
+ */
 export interface AwsSdkMatchers<R = unknown> {
+    /**
+     * Assert that a command was received at least once.
+     * @param command - The command constructor to check for
+     */
     toHaveReceivedCommand<TInput extends object, TOutput extends MetadataBearer>(command: CommandConstructor<TInput, TOutput>): R;
+    /**
+     * Assert that a command was received exactly N times.
+     * @param command - The command constructor to check for
+     * @param times - The exact number of times
+     */
     toHaveReceivedCommandTimes<TInput extends object, TOutput extends MetadataBearer>(command: CommandConstructor<TInput, TOutput>, times: number): R;
+    /**
+     * Assert that a command was received with specific input.
+     * @param command - The command constructor to check for
+     * @param input - The expected input parameters
+     */
     toHaveReceivedCommandWith<TInput extends object, TOutput extends MetadataBearer>(command: CommandConstructor<TInput, TOutput>, input: TInput): R;
+    /**
+     * Assert that the Nth command call matches expectations.
+     * @param n - The call number (1-indexed)
+     * @param command - The command constructor to check for
+     * @param input - The expected input parameters
+     */
     toHaveReceivedNthCommandWith<TInput extends object, TOutput extends MetadataBearer>(n: number, command: CommandConstructor<TInput, TOutput>, input: TInput): R;
+    /**
+     * Assert that only expected commands were received.
+     * @param expectedCommands - Array of allowed command constructors
+     */
     toHaveReceivedNoOtherCommands<TInput extends object, TOutput extends MetadataBearer>(expectedCommands?: CommandConstructor<TInput, TOutput>[]): R;
 }
 export type { MatcherResult };

package/lib/mock-client.d.ts

@@ -3,6 +3,27 @@ import { HttpHandlerOptions, MetadataBearer } from '@smithy/types';
 import { Mock } from 'vitest';
 import { PaginatorOptions } from './utils/paginator-helpers.js';
 import { StreamInput } from './utils/stream-helpers.js';
+/**
+ * Set global debug mode for all mocks.
+ * When enabled, all mocks will log debug information unless explicitly disabled at the mock level.
+ *
+ * @param enabled - Whether to enable debug logging globally
+ *
+ * @example
+ * ```typescript
+ * import { setGlobalDebug, mockClient } from 'aws-sdk-vitest-mock';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * // Enable debug for all mocks
+ * setGlobalDebug(true);
+ *
+ * const s3Mock = mockClient(S3Client); // Automatically has debug enabled
+ *
+ * // Disable debug for a specific mock
+ * s3Mock.disableDebug(); // This mock won't log, but others will
+ * ```
+ */
+export declare function setGlobalDebug(enabled: boolean): void;
 export type StructuralCommand<TInput extends object, TOutput extends MetadataBearer> = SmithyCommand<TInput, TOutput, any, any, any> | {
     readonly input: TInput;
     readonly __awsSdkVitestMockOutput?: TOutput;
@@ -23,57 +44,474 @@ type CommandHandler<TInput extends object = object, TOutput extends MetadataBear
 interface MockOptions {
     strict?: boolean;
 }
+/**
+ * Client stub for configuring and managing mock behaviors for an AWS SDK client.
+ *
+ * @category Core Functions
+ *
+ * @example
+ * ```typescript
+ * const s3Mock = mockClient(S3Client);
+ *
+ * // Configure mock behavior
+ * s3Mock.on(GetObjectCommand).resolves({ Body: 'data' });
+ *
+ * // Mock works as configured
+ * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file.txt' }));
+ * expect(s3Mock.calls()).toHaveLength(1);
+ *
+ * // Reset clears call history but keeps mock configuration
+ * s3Mock.reset();
+ * expect(s3Mock.calls()).toHaveLength(0);
+ *
+ * // Mock still works after reset
+ * await client.send(new GetObjectCommand({ Bucket: 'test', Key: 'file.txt' }));
+ * expect(s3Mock.calls()).toHaveLength(1);
+ * ```
+ */
 export interface AwsClientStub<TClient extends AnyClient = AnyClient> {
+    /**
+     * The client instance being mocked (undefined for class-level mocks).
+     * @readonly
+     */
     readonly client: TClient | undefined;
+    /**
+     * Configure mock behavior for a specific command.
+     *
+     * @param command - The AWS SDK command constructor to mock
+     * @param request - Optional partial input to match against (uses partial matching by default)
+     * @param options - Optional configuration for strict matching
+     * @returns A command stub for configuring mock responses
+     *
+     * @example Match any input
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).resolves({ Body: 'data' });
+     * ```
+     *
+     * @example Match specific input (partial)
+     * ```typescript
+     * s3Mock.on(GetObjectCommand, { Bucket: 'my-bucket' }).resolves({ Body: 'bucket data' });
+     * ```
+     *
+     * @example Match exact input (strict)
+     * ```typescript
+     * s3Mock.on(GetObjectCommand, { Bucket: 'my-bucket', Key: 'file.txt' }, { strict: true })
+     *   .resolves({ Body: 'exact match' });
+     * ```
+     */
     on: <TCtor extends AwsCommandConstructor>(command: TCtor, request?: Partial<CommandInputType<TCtor>>, options?: MockOptions) => AwsCommandStub<CommandInputType<TCtor>, CommandOutputType<TCtor>, TClient>;
+    /**
+     * Clear mock call history while preserving configured behaviors.
+     * Mock configurations remain active after reset, only the call history is cleared.
+     * Use this between tests when you want to reuse the same mock setup.
+     *
+     * @example
+     * ```typescript
+     * afterEach(() => {
+     *   s3Mock.reset();
+     * });
+     * ```
+     */
     reset: () => void;
+    /**
+     * Restore the original client behavior and clear all mocks.
+     * After calling restore, the client will no longer be mocked.
+     *
+     * @example
+     * ```typescript
+     * afterAll(() => {
+     *   s3Mock.restore();
+     * });
+     * ```
+     */
     restore: () => void;
+    /**
+     * Get an array of all commands that were sent to the client.
+     *
+     * @returns Array of AWS SDK commands
+     *
+     * @example
+     * ```typescript
+     * const calls = s3Mock.calls();
+     * console.log(calls.length); // Number of commands sent
+     * console.log(calls[0].input); // Input of first command
+     * ```
+     */
     calls: () => AwsSdkCommand[];
     /** @internal - For use by matchers only */
     __rawCalls: () => ReturnType<Mock["mock"]["calls"]["slice"]>;
+    /**
+     * Enable debug logging to see detailed information about mock configuration and interactions.
+     * Logs both mock setup (when `.on()`, `.resolves()`, etc. are called) and command execution details.
+     * Useful for troubleshooting mock configurations and why commands aren't matching expected mocks.
+     *
+     * @example
+     * ```typescript
+     * s3Mock.enableDebug();
+     * // Logs will appear for:
+     * // - Mock configuration (when .on(), .resolves(), etc. are called)
+     * // - Command execution (incoming commands and inputs)
+     * // - Mock matching results and reasons for failures
+     * // - Lifecycle events (reset, restore)
+     * ```
+     */
     enableDebug: () => void;
+    /**
+     * Disable debug logging for mock configuration and interactions.
+     *
+     * @example
+     * ```typescript
+     * s3Mock.disableDebug();
+     * ```
+     */
     disableDebug: () => void;
 }
+/**
+ * Command stub for configuring mock behaviors for a specific AWS SDK command.
+ * Provides a fluent API for setting up various mock responses and behaviors.
+ *
+ * @category Command Stub
+ *
+ * @example Basic usage
+ * ```typescript
+ * const s3Mock = mockClient(S3Client);
+ * s3Mock.on(GetObjectCommand).resolves({ Body: 'data' });
+ * ```
+ *
+ * @example Chaining multiple behaviors
+ * ```typescript
+ * s3Mock.on(PutObjectCommand)
+ *   .resolvesOnce({ ETag: '123' })
+ *   .resolvesOnce({ ETag: '456' })
+ *   .resolves({ ETag: 'default' });
+ * ```
+ */
 export interface AwsCommandStub<TInput extends object, TOutput extends MetadataBearer, TClient extends AnyClient = AnyClient> {
-    /** Set a permanent mock response (used after all once handlers are consumed) */
+    /**
+     * Set a permanent mock response that will be used after all one-time handlers are consumed.
+     *
+     * @param output - Partial output object to return when the command is called
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).resolves({ Body: 'file contents' });
+     * ```
+     */
     resolves: (output: Partial<TOutput>) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Set a permanent mock rejection (used after all once handlers are consumed) */
+    /**
+     * Set a permanent mock rejection that will be used after all one-time handlers are consumed.
+     *
+     * @param error - Error object or error message string
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).rejects(new Error('Access denied'));
+     * ```
+     */
     rejects: (error: Error | string) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Set a permanent custom handler (used after all once handlers are consumed) */
+    /**
+     * Set a permanent custom handler function that will be used after all one-time handlers are consumed.
+     *
+     * @param fn - Handler function that receives input and client instance
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).callsFake(async (input) => {
+     *   return { Body: `Contents of ${input.Key}` };
+     * });
+     * ```
+     */
     callsFake: (fn: CommandHandler<TInput, TOutput, TClient>) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Add a one-time mock response (consumed in order) */
+    /**
+     * Add a one-time mock response that will be consumed in order.
+     *
+     * @param output - Partial output object to return
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand)
+     *   .resolvesOnce({ Body: 'first call' })
+     *   .resolvesOnce({ Body: 'second call' });
+     * ```
+     */
     resolvesOnce: (output: Partial<TOutput>) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Add a one-time mock rejection (consumed in order) */
+    /**
+     * Add a one-time mock rejection that will be consumed in order.
+     *
+     * @param error - Error object or error message string
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand)
+     *   .rejectsOnce('First call fails')
+     *   .resolves({ Body: 'second call succeeds' });
+     * ```
+     */
     rejectsOnce: (error: Error | string) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Add a one-time custom handler (consumed in order) */
+    /**
+     * Add a one-time custom handler that will be consumed in order.
+     *
+     * @param fn - Handler function that receives input and client instance
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand)
+     *   .callsFakeOnce(async (input) => ({ Body: 'once' }))
+     *   .resolves({ Body: 'permanent' });
+     * ```
+     */
     callsFakeOnce: (fn: CommandHandler<TInput, TOutput, TClient>) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Set a permanent stream response for S3-like operations */
+    /**
+     * Set a permanent stream response for S3-like operations.
+     *
+     * @param data - String, Buffer, or Readable stream
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).resolvesStream('file contents');
+     * ```
+     */
     resolvesStream: (data: StreamInput) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Set a one-time stream response for S3-like operations */
+    /**
+     * Set a one-time stream response for S3-like operations.
+     *
+     * @param data - String, Buffer, or Readable stream
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand)
+     *   .resolvesStreamOnce('first stream')
+     *   .resolvesStream('default stream');
+     * ```
+     */
     resolvesStreamOnce: (data: StreamInput) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Set a permanent mock response with delay */
+    /**
+     * Set a permanent mock response with a delay in milliseconds.
+     *
+     * @param output - Partial output object to return
+     * @param delayMs - Delay in milliseconds before resolving
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).resolvesWithDelay({ Body: 'data' }, 1000);
+     * ```
+     */
     resolvesWithDelay: (output: Partial<TOutput>, delayMs: number) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Set a permanent mock rejection with delay */
+    /**
+     * Set a permanent mock rejection with a delay in milliseconds.
+     *
+     * @param error - Error object or error message string
+     * @param delayMs - Delay in milliseconds before rejecting
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).rejectsWithDelay('Timeout', 5000);
+     * ```
+     */
     rejectsWithDelay: (error: Error | string, delayMs: number) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Reject with S3 NoSuchKey error */
+    /**
+     * Reject with an S3 NoSuchKey error.
+     *
+     * @param key - Optional key name for error message
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).rejectsWithNoSuchKey('missing-file.txt');
+     * ```
+     */
     rejectsWithNoSuchKey: (key?: string) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Reject with S3 NoSuchBucket error */
+    /**
+     * Reject with an S3 NoSuchBucket error.
+     *
+     * @param bucket - Optional bucket name for error message
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).rejectsWithNoSuchBucket('my-bucket');
+     * ```
+     */
     rejectsWithNoSuchBucket: (bucket?: string) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Reject with AccessDenied error */
+    /**
+     * Reject with an AccessDenied error.
+     *
+     * @param resource - Optional resource name for error message
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).rejectsWithAccessDenied('private-file.txt');
+     * ```
+     */
     rejectsWithAccessDenied: (resource?: string) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Reject with DynamoDB ResourceNotFound error */
+    /**
+     * Reject with a DynamoDB ResourceNotFound error.
+     *
+     * @param resource - Optional resource name for error message
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * dynamoMock.on(GetItemCommand).rejectsWithResourceNotFound('MyTable');
+     * ```
+     */
     rejectsWithResourceNotFound: (resource?: string) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Reject with DynamoDB ConditionalCheckFailed error */
+    /**
+     * Reject with a DynamoDB ConditionalCheckFailed error.
+     *
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * dynamoMock.on(PutItemCommand).rejectsWithConditionalCheckFailed();
+     * ```
+     */
     rejectsWithConditionalCheckFailed: () => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Reject with Throttling error */
+    /**
+     * Reject with a Throttling error.
+     *
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).rejectsWithThrottling();
+     * ```
+     */
     rejectsWithThrottling: () => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Reject with InternalServerError */
+    /**
+     * Reject with an InternalServerError.
+     *
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).rejectsWithInternalServerError();
+     * ```
+     */
     rejectsWithInternalServerError: () => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Set paginated responses for AWS pagination */
+    /**
+     * Set paginated responses for AWS pagination patterns.
+     *
+     * Tokens are automatically set to the last item of each page, which works for both
+     * DynamoDB (object tokens) and S3 (object tokens).
+     *
+     * @param items - Array of items to paginate (use marshalled items for DynamoDB)
+     * @param options - Pagination configuration options
+     * @returns The command stub for chaining
+     *
+     * @example DynamoDB pagination with marshalled data
+     * ```typescript
+     * import { marshall } from '@aws-sdk/util-dynamodb';
+     *
+     * const users = [
+     *   { id: "user-1", name: "Alice" },
+     *   { id: "user-2", name: "Bob" }
+     * ];
+     * const marshalledUsers = users.map(u => marshall(u));
+     *
+     * dynamoMock.on(ScanCommand).resolvesPaginated(marshalledUsers, {
+     *   pageSize: 1,
+     *   tokenKey: "LastEvaluatedKey",
+     *   inputTokenKey: "ExclusiveStartKey"
+     * });
+     *
+     * // LastEvaluatedKey will be the marshalled last item (object, not string)
+     * const result = await client.send(new ScanCommand({ TableName: "Users" }));
+     * // result.LastEvaluatedKey = { id: { S: "user-1" }, name: { S: "Alice" } }
+     * ```
+     *
+     * @example S3 pagination
+     * ```typescript
+     * const objects = [
+     *   { Key: 'file1.txt', Size: 100 },
+     *   { Key: 'file2.txt', Size: 200 }
+     * ];
+     *
+     * s3Mock.on(ListObjectsV2Command).resolvesPaginated(objects, {
+     *   pageSize: 1,
+     *   itemsKey: "Contents",
+     *   tokenKey: "NextContinuationToken",
+     *   inputTokenKey: "ContinuationToken"
+     * });
+     *
+     * // NextContinuationToken will be the last object from the page
+     * const result = await client.send(new ListObjectsV2Command({ Bucket: "bucket" }));
+     * // result.NextContinuationToken = { Key: 'file1.txt', Size: 100 }
+     * ```
+     */
     resolvesPaginated: <T = unknown>(items: T[], options?: PaginatorOptions) => AwsCommandStub<TInput, TOutput, TClient>;
-    /** Load response from file (JSON files are parsed, others returned as strings) */
+    /**
+     * Load response from a file. JSON files are parsed, others returned as strings.
+     *
+     * @param filePath - Path to the file to load
+     * @returns The command stub for chaining
+     *
+     * @example
+     * ```typescript
+     * s3Mock.on(GetObjectCommand).resolvesFromFile('./fixtures/response.json');
+     * ```
+     */
     resolvesFromFile: (filePath: string) => AwsCommandStub<TInput, TOutput, TClient>;
 }
+/**
+ * Create a mock for an AWS SDK client class.
+ *
+ * Use this function when you want to mock all instances of a client class.
+ *
+ * @category Core Functions
+ *
+ * @param clientConstructor - The AWS SDK client class to mock
+ * @returns A client stub for configuring mock behaviors
+ *
+ * @example
+ * ```typescript
+ * import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+ * import { mockClient } from 'aws-sdk-vitest-mock';
+ *
+ * const s3Mock = mockClient(S3Client);
+ *
+ * s3Mock.on(GetObjectCommand).resolves({ Body: 'file contents' });
+ *
+ * const client = new S3Client({});
+ * const result = await client.send(new GetObjectCommand({ Bucket: 'my-bucket', Key: 'file.txt' }));
+ * // result.Body === 'file contents'
+ * ```
+ */
 export declare const mockClient: <TClient extends AnyClient>(clientConstructor: ClientConstructor<TClient>) => AwsClientStub<TClient>;
+/**
+ * Create a mock for a specific AWS SDK client instance.
+ *
+ * Use this function when you want to mock a single client instance.
+ *
+ * @category Core Functions
+ *
+ * @param clientInstance - The AWS SDK client instance to mock
+ * @returns A client stub for configuring mock behaviors
+ *
+ * @example
+ * ```typescript
+ * import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+ * import { mockClientInstance } from 'aws-sdk-vitest-mock';
+ *
+ * const client = new S3Client({});
+ * const s3Mock = mockClientInstance(client);
+ *
+ * s3Mock.on(GetObjectCommand).resolves({ Body: 'file contents' });
+ *
+ * const result = await client.send(new GetObjectCommand({ Bucket: 'my-bucket', Key: 'file.txt' }));
+ * // result.Body === 'file contents'
+ * ```
+ */
 export declare const mockClientInstance: <TClient extends AnyClient>(clientInstance: TClient) => AwsClientStub<AnyClient>;
 export {};

package/lib/utils/debug-logger.d.ts

@@ -1,7 +1,9 @@
 export interface DebugLogger {
     enabled: boolean;
+    explicitlySet: boolean;
     log: (message: string, data?: unknown) => void;
+    logDirect: (message: string, data?: unknown) => void;
 }
-export declare function createDebugLogger(): DebugLogger;
-export declare function enableDebug(logger: DebugLogger): void;
-export declare function disableDebug(logger: DebugLogger): void;
+export declare const createDebugLogger: (initialEnabled?: boolean) => DebugLogger;
+export declare const enableDebug: (logger: DebugLogger) => void;
+export declare const disableDebug: (logger: DebugLogger) => void;