aws-sdk-vitest-mock 0.3.1 → 0.5.0

package/lib/utils/paginator-helpers.d.ts

@@ -1,6 +1,69 @@
+/**
+ * Configuration options for paginated responses.
+ *
+ * Tokens are automatically set to the last item of each page, which works for both
+ * DynamoDB-style pagination (object tokens) and S3-style pagination (object tokens).
+ *
+ * @example DynamoDB configuration
+ * ```typescript
+ * {
+ *   pageSize: 10,
+ *   tokenKey: "LastEvaluatedKey",      // DynamoDB response key
+ *   inputTokenKey: "ExclusiveStartKey", // DynamoDB request key
+ *   itemsKey: "Items"
+ * }
+ * ```
+ *
+ * @example S3 configuration
+ * ```typescript
+ * {
+ *   pageSize: 50,
+ *   tokenKey: "NextContinuationToken",  // S3 response key
+ *   inputTokenKey: "ContinuationToken",  // S3 request key
+ *   itemsKey: "Contents"
+ * }
+ * ```
+ */
 export interface PaginatorOptions {
+    /**
+     * Number of items per page.
+     * @default 10
+     */
     pageSize?: number;
+    /**
+     * Property name for the pagination token in the response.
+     * The token will be set to the last item of the page.
+     *
+     * Common values:
+     * - DynamoDB: "LastEvaluatedKey"
+     * - S3: "NextContinuationToken"
+     * - Generic: "NextToken"
+     *
+     * @default "NextToken"
+     */
     tokenKey?: string;
+    /**
+     * Property name for the pagination token in the request.
+     * If not specified, uses the same value as tokenKey.
+     *
+     * Use this when the service uses different names for input and output tokens.
+     *
+     * Common values:
+     * - DynamoDB: "ExclusiveStartKey" (when tokenKey is "LastEvaluatedKey")
+     * - S3: "ContinuationToken" (when tokenKey is "NextContinuationToken")
+     *
+     * @default Same as tokenKey
+     */
+    inputTokenKey?: string;
+    /**
+     * Property name for the items array in the response.
+     *
+     * Common values:
+     * - DynamoDB: "Items"
+     * - S3: "Contents"
+     *
+     * @default "Items"
+     */
     itemsKey?: string;
 }
 export interface PaginatedResponse<T = unknown> {
@@ -10,4 +73,26 @@ export interface PaginatedResponse<T = unknown> {
     Items?: T[];
     Contents?: T[];
 }
+/**
+ * Creates paginated responses from an array of items.
+ *
+ * Each page's token is set to the last item of that page, enabling proper
+ * pagination for services like DynamoDB (where tokens are objects) and S3.
+ *
+ * @param items - Array of items to paginate
+ * @param options - Pagination configuration options
+ * @returns Array of paginated responses, each containing a subset of items
+ *
+ * @example
+ * ```typescript
+ * const items = [1, 2, 3, 4, 5];
+ * const responses = createPaginatedResponses(items, { pageSize: 2 });
+ * // Returns:
+ * // [
+ * //   { Items: [1, 2], NextToken: 2 },
+ * //   { Items: [3, 4], NextToken: 4 },
+ * //   { Items: [5] }
+ * // ]
+ * ```
+ */
 export declare function createPaginatedResponses<T>(items: T[], options?: PaginatorOptions): PaginatedResponse<T>[];

package/{matchers-C6AtmwWz.js → matchers-ClGOsQx8.js}

@@ -13,6 +13,23 @@ const e = {
     (a) => Array.isArray(a) && a.length > 0
   ) : [];
 }, f = {
+  /**
+   * 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(t, c) {
     const a = $(t), r = a.some((o) => o[0] instanceof c), m = c.name;
     return {
@@ -25,6 +42,25 @@ const e = {
       }
     };
   },
+  /**
+   * 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(t, c, a) {
     const r = $(t).filter(
       (n) => n[0] instanceof c
@@ -34,6 +70,27 @@ const e = {
       message: () => m ? `Expected AWS SDK mock not to have received command ${o} ${a} times` : `Expected AWS SDK mock to have received command ${o} ${a} times, but received ${r.length} times`
     };
   },
+  /**
+   * 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(t, c, a) {
     const r = $(t).filter(
       (n) => n[0] instanceof c
@@ -70,6 +127,29 @@ ${S}`;
       }
     };
   },
+  /**
+   * 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(t, c, a, r) {
     const m = $(t), o = m[c - 1], n = o?.[0], d = n?.input, g = !!o && n instanceof a && this.equals(d, r), l = a.name;
     return {
@@ -101,6 +181,24 @@ ${u}`;
       }
     };
   },
+  /**
+   * 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(t, c = []) {
     const r = $(t).filter((o) => {
       const n = o[0];
@@ -120,5 +218,6 @@ ${u}`;
   }
 };
 export {
+  e as c,
   f as m
 };

package/{matchers-Rq18z2C7.cjs → matchers-Dkkl4vtx.cjs}

@@ -13,4 +13,4 @@ ${y}`}if(!o){const i=e.magenta(c.toString()),v=e.gray(`only received ${m.length}
 ${p}
 
 ${s}:
-${u}`}}},toHaveReceivedNoOtherCommands(t,c=[]){const r=$(t).filter(o=>{const n=o[0];return!c.some(d=>n instanceof d)}),m=r.length===0;return{pass:m,message:()=>{if(m)return`Expected AWS SDK mock to have received other commands besides ${e.green(c.map(n=>n.name).join(", "))}`;const o=r.map(n=>n[0].constructor?.name??"Unknown");return`Expected AWS SDK mock to have received ${e.gray("no other commands")}, but received: ${e.red(o.join(", "))}`}}}};exports.matchers=f;
+${u}`}}},toHaveReceivedNoOtherCommands(t,c=[]){const r=$(t).filter(o=>{const n=o[0];return!c.some(d=>n instanceof d)}),m=r.length===0;return{pass:m,message:()=>{if(m)return`Expected AWS SDK mock to have received other commands besides ${e.green(c.map(n=>n.name).join(", "))}`;const o=r.map(n=>n[0].constructor?.name??"Unknown");return`Expected AWS SDK mock to have received ${e.gray("no other commands")}, but received: ${e.red(o.join(", "))}`}}}};exports.colors=e;exports.matchers=f;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aws-sdk-vitest-mock",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -24,8 +24,16 @@
   "license": "MIT",
   "author": "sudokar",
   "scripts": {
+    "ci": "bun install --frozen-lockfile",
     "prepare": "husky",
-    "prepublishOnly": "HUSKY=0"
+    "prepublishOnly": "HUSKY=0",
+    "lint": "nx lint",
+    "lint:fix": "nx lint --fix",
+    "test": "nx test",
+    "build": "nx build",
+    "docs": "typedoc && touch docs/.nojekyll",
+    "docs:watch": "typedoc --watch",
+    "docs:serve": "bun run docs && bunx http-server docs -o"
   },
   "nx": {
     "includedScripts": []
@@ -61,6 +69,7 @@
     "lint-staged": "16.2.7",
     "nx": "22.2.2",
     "prettier": "3.7.4",
+    "typedoc": "0.28.15",
     "typescript": "5.9.3",
     "typescript-eslint": "8.49.0",
     "vite": "7.2.7",

package/vitest-setup.cjs

@@ -1 +1 @@
-"use strict";const e=require("vitest"),t=require("./matchers-Rq18z2C7.cjs");e.expect.extend(t.matchers);
+"use strict";const e=require("vitest"),t=require("./matchers-Dkkl4vtx.cjs");e.expect.extend(t.matchers);

package/vitest-setup.js

@@ -1,3 +1,3 @@
 import { expect as m } from "vitest";
-import { m as e } from "./matchers-C6AtmwWz.js";
+import { m as e } from "./matchers-ClGOsQx8.js";
 m.extend(e);