@juit/lib-aws-mock 1.0.0

package/LICENSE.md

@@ -0,0 +1,211 @@
+# Apache License
+
+Version 2.0, January 2004
+
+[http://www.apache.org/licenses/](http://www.apache.org/licenses/)
+
+##### TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+### 1. Definitions.
+
+"**License**" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"**Licensor**" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"**Legal Entity**" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"**control**" means **(i)** the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, _or_ **(ii)** ownership of fifty percent (50%) or more of
+the outstanding shares, _or_ **(iii)** beneficial ownership of such
+entity.
+
+"**You**" (or "**Your**") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"**Source**" form shall mean the preferred form for making
+modifications, including but not limited to software source code,
+documentation source, and configuration files.
+
+"**Object**" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but not
+limited to compiled object code, generated documentation, and
+conversions to other media types.
+
+"**Work**" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work (an example
+is provided in the Appendix below).
+
+"**Derivative Works**" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"**Contribution**" shall mean any work of authorship, including the
+original version of the Work and any modifications or additions to that
+Work or Derivative Works thereof, that is intentionally submitted to
+Licensor for inclusion in the Work by the copyright owner or by an
+individual or Legal Entity authorized to submit on behalf of the
+copyright owner. For the purposes of this definition, "**submitted**"
+means any form of electronic, verbal, or written communication sent to
+the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "**Not a
+Contribution**".
+
+"**Contributor**" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+### 2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor
+hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+royalty-free, irrevocable copyright license to reproduce, prepare
+Derivative Works of, publicly display, publicly perform, sublicense,
+and distribute the Work and such Derivative Works in Source or Object
+form.
+
+### 3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor
+hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and
+otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily
+infringed by their Contribution(s) alone or by combination of their
+Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+the Work or a Contribution incorporated within the Work constitutes
+direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+### 4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works
+thereof in any medium, with or without modifications, and in Source or
+Object form, provided that You meet the following conditions:
+
+<ol type="a">
+  <li>You must give any other recipients of the Work or Derivative Works
+    a copy of this License; and
+  <li>You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+  <li>You must retain, in the Source form of any Derivative Works that
+    You distribute, all copyright, patent, trademark, and attribution
+    notices from the Source form of the Work, excluding those notices
+    that do not pertain to any part of the Derivative Works; and
+  <li>If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained within
+    such NOTICE file, excluding those notices that do not pertain to any
+    part of the Derivative Works, in at least one of the following
+    places: within a NOTICE text file distributed as part of the
+    Derivative Works; within the Source form or documentation, if
+    provided along with the Derivative Works; or, within a display
+    generated by the Derivative Works, if and wherever such third-party
+    notices normally appear. The contents of the NOTICE file are for
+    informational purposes only and do not modify the License. You may
+    add Your own attribution notices within Derivative Works that You
+    distribute, alongside or as an addendum to the NOTICE text from the
+    Work, provided that such additional attribution notices cannot be
+    construed as modifying the License.
+</ol>
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated
+in this License.
+
+### 5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally
+submitted for inclusion in the Work by You to the Licensor shall be
+under the terms and conditions of this License, without any additional
+terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+### 6. Trademarks.
+
+This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of
+the Work and reproducing the content of the NOTICE file.
+
+### 7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor
+provides the Work (and each Contributor provides its Contributions) on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR
+A PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+### 8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including
+negligence), contract, or otherwise, unless required by applicable law
+(such as deliberate and grossly negligent acts) or agreed to in writing,
+shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or
+inability to use the Work (including but not limited to damages for loss
+of goodwill, work stoppage, computer failure or malfunction, or any and
+all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+### 9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may
+choose to offer, and charge a fee for, acceptance of support, warranty,
+indemnity, or other liability obligations and/or rights consistent with
+this License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf of any
+other Contributor, and only if You agree to indemnify, defend, and hold
+each Contributor harmless for any liability incurred by, or claims
+asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+##### END OF TERMS AND CONDITIONS
+
+## APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include the
+brackets!)  The text should be enclosed in the appropriate comment
+syntax for the file format. We also recommend that a file or class name
+and description of purpose be included on the same "printed page" as the
+copyright notice for easier identification within third-party archives.
+
+> #### Copyright [yyyy] [name of copyright owner]
+>
+> Licensed under the Apache License, Version 2.0 (the "License");
+> you may not use this file except in compliance with the License.
+> You may obtain a copy of the License at
+>
+> [http://www.apache.org/licenses/](http://www.apache.org/licenses/)
+>
+> Unless required by applicable law or agreed to in writing, software
+> distributed under the License is distributed on an "AS IS" BASIS,
+> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+> See the License for the specific language governing permissions and
+> limitations under the License.

package/NOTICE.md

@@ -0,0 +1,13 @@
+# Copyright 2021-2023 Juit GmbH
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+[http://www.apache.org/licenses/](http://www.apache.org/licenses/)
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,126 @@
+# Easy Mocking for AWS SDK v3
+
+A simple way to create mocks for the AWS SDK v3 library.
+
+* [Mocking commands](#mocking-commands)
+* [Call Tracing](#call-tracing)
+* [State for Handlers](#state-for-handlers)
+* [Resetting](#resetting)
+* [Destroying](#destroying)
+* [Typical Test Scenario](#typical-test-scenario)
+* [License](LICENSE.md)
+* [Copyright Notice](NOTICE.md)
+
+
+## Mocking commands
+
+Mocking commands for an AWS client is quite easy. For example:
+
+```typescript
+import { AWSMock } from '@juit/lib-aws-mock'
+import {
+  AssumeRoleCommand,
+  GetCallerIdentityCommand,
+  STS,
+} from '@aws-sdk/client-sts'
+
+const mock = new AWSMock(STS)
+  .on(GetCallerIdentityCommand, (input, state) => {
+    // here `input` will be the parameter passed to `getCallerIdentity(...)`
+    // and `state` will be whatever was passed to `mock.setState(...)`
+    return { Account: 'the account' }
+  })
+  .on(AssumeRoleCommand, (input, state) => {
+    // ... mocked implementation lives here...
+  })
+
+const sts = new STS({})
+const identity = await sts.getCallerIdentity({})
+// here `identity` will be `{ Account: 'the account' }`
+// as returned by our handler configured in the mock
+```
+
+
+## Call Tracing
+
+Instances of `AWSMock` provide a `getCalls()` function returning
+all calls invoked on the mock. Calls will contain the following:
+
+* `command`: The _string_ name of the command invoked
+* `input`: The input given to the call
+* `success`: A _boolean_ indicating whether the call succeeded or not
+
+```typescript
+const identity = await sts.getCallerIdentity({})
+
+const calls = mock.calls()
+// here `calls` will be:
+// {
+//   command: 'GetCallerIdentityCommand',
+//   input: '',
+//   success: true,
+// }
+```
+
+
+## State for Handlers
+
+Instances of `AWSMock` provide a `setState(...)` function which can be used
+to pass extra data to handlers:
+
+```typescript
+const mock = new AWSMock<string>(STS)
+  .on(GetCallerIdentityCommand, (input, state) => {
+    // state will have a `string` type
+    return { Account: state || 'the account' }
+  })
+
+const sts = new STS({})
+
+const identity1 = await sts.getCallerIdentity({})
+// here identity1 will be `{ Account: 'the account' }`
+
+mock.setState('another account') // set the stae
+const identity2 = await sts.getCallerIdentity({})
+// here identity2 will be `{ Account: 'another account' }`
+```
+
+
+## Resetting
+
+Reseting [calls](#call-tracing) and [state](#state-for-handlers) is as easy as
+calling the `reset()` function on the mock instance.
+
+
+## Destroying
+
+Destroying the mock instance and un-hooking it from the client can be done
+calling the `destroy()` function on the mock instance.
+
+
+## Typical Test Scenario
+
+A typical test scenario can look somehow like this:
+
+```typescript
+describe('My Suite', () => {
+  let mock: AWSMock
+
+  beforeAll(() => {
+    mock = new AWSMock(STS)
+      .on(GetCallerIdentityCommand, (input, state) => {
+        // ... mocked implementation lives here...
+      })
+      .on(AssumeRoleCommand, (input, state) => {
+        // ... mocked implementation lives here...
+      })
+  })
+
+  afterAll(() => mock.destroy())
+  afterEach(() => mock.reset())
+
+  it('should run this spec', async () => {
+    // ... here's your spec...
+  })
+})
+```

package/dist/index.cjs

@@ -0,0 +1,107 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var src_exports = {};
+__export(src_exports, {
+  AWSMock: () => AWSMock
+});
+module.exports = __toCommonJS(src_exports);
+var import_node_crypto = require("node:crypto");
+var AWSMock = class {
+  // Overload to hide private parameter
+  constructor(_client) {
+    this._client = _client;
+    this._send = _client.prototype.send;
+    const clientName = _client.name || /* coverage ignore next */
+    "[Unknown Client]";
+    _client.prototype.send = (_command, ..._args) => {
+      const commandProto = Object.getPrototypeOf(_command);
+      const commandConstuctor = commandProto.constructor;
+      const commandName = commandConstuctor?.name || /* coverage ignore next */
+      "[Unknown Command]";
+      const lastArgument = _args.pop();
+      const cb = typeof lastArgument === "function" ? lastArgument : void 0;
+      const promise = Promise.resolve().then(async () => {
+        const handler = this._handlers.get(commandConstuctor);
+        if (!handler)
+          throw new Error(`No mock for "${clientName}.${commandName}"`);
+        const result = await handler(_command.input, this._state);
+        if (!result)
+          throw new Error(`Mock for "${clientName}.${commandName}" returned no result`);
+        if (!result.$metadata)
+          result.$metadata = { httpStatusCode: 200 };
+        if (!result.$metadata.requestId)
+          result.$metadata.requestId = (0, import_node_crypto.randomUUID)();
+        return result;
+      }).then((result) => {
+        this._calls.push({ command: commandName, input: _command.input, success: true });
+        return result;
+      }, (error) => {
+        this._calls.push({ command: commandName, input: _command.input, success: false });
+        throw error;
+      });
+      if (cb)
+        promise.then((result) => cb(null, result), (error) => cb(error));
+      return promise;
+    };
+  }
+  /** All configured command handlers */
+  _handlers = /* @__PURE__ */ new Map();
+  /** The _original_ (unmocked) `send(...)` method from the client prototype */
+  _send;
+  /** Current record of all calls handled by this instance */
+  _calls = [];
+  /** Current state to be passed to handlers */
+  _state = void 0;
+  /** Associate a _state_ with this instance, to be passed to handlers */
+  setState(state) {
+    this._state = state;
+  }
+  /** Return the list of calls executed by this instance */
+  getCalls() {
+    return this._calls;
+  }
+  /**
+   * Reset this instance by zeroing the {@link AWSMock.calls calls} and wiping
+   * the {@link AWSMock.state state}.
+   *
+   * @returns The list of calls executed by this instance before reset.
+   */
+  reset() {
+    const calls = this._calls;
+    delete this._state;
+    this._calls = [];
+    return calls;
+  }
+  /** Destroy this instance, restoring the mocked methods */
+  destroy() {
+    this._client.prototype.send = this._send;
+  }
+  /** Setup a _handler_ for a specific {@link Command} */
+  on(command, handler) {
+    this._handlers.set(command, handler);
+    return this;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AWSMock
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAA2B;AAmCpB,IAAM,UAAN,MAA2B;AAAA;AAAA,EAahC,YAAoB,SAAiC;AAAjC;AAElB,SAAK,QAAQ,QAAQ,UAAU;AAG/B,UAAM,aAAa,QAAQ;AAAA,IAAmC;AAG9D,YAAQ,UAAU,OAAO,CAAC,aAAyB,UAA+B;AAChF,YAAM,eAAe,OAAO,eAAe,QAAQ;AACnD,YAAM,oBAAoB,aAAa;AACvC,YAAM,cAAc,mBAAmB;AAAA,MAAmC;AAG1E,YAAM,eAAe,MAAM,IAAI;AAC/B,YAAM,KACJ,OAAO,iBAAiB,aAAa,eAAe;AAGtD,YAAM,UAAU,QAAQ,QAAQ,EAAE,KAAK,YAAY;AAEjD,cAAM,UAAU,KAAK,UAAU,IAAI,iBAAiB;AACpD,YAAI,CAAE;AAAS,gBAAM,IAAI,MAAM,gBAAgB,cAAc,cAAc;AAG3E,cAAM,SAAyB,MAAM,QAAQ,SAAS,OAAO,KAAK,MAAM;AAGxE,YAAI,CAAE;AAAQ,gBAAM,IAAI,MAAM,aAAa,cAAc,iCAAiC;AAG1F,YAAI,CAAE,OAAO;AAAW,iBAAO,YAAY,EAAE,gBAAgB,IAAI;AACjE,YAAI,CAAE,OAAO,UAAU;AAAW,iBAAO,UAAU,gBAAY,+BAAW;AAG1E,eAAO;AAAA,MACT,CAAC,EAAE,KAAK,CAAC,WAAW;AAElB,aAAK,OAAO,KAAK,EAAE,SAAS,aAAa,OAAO,SAAS,OAAO,SAAS,KAAK,CAAC;AAC/E,eAAO;AAAA,MACT,GAAG,CAAC,UAAU;AAEZ,aAAK,OAAO,KAAK,EAAE,SAAS,aAAa,OAAO,SAAS,OAAO,SAAS,MAAM,CAAC;AAChF,cAAM;AAAA,MACR,CAAC;AAGD,UAAI;AAAI,gBAAQ,KAAK,CAAC,WAAW,GAAG,MAAM,MAAM,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC;AACvE,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA,EA7DQ,YAAY,oBAAI,IAAuD;AAAA;AAAA,EAEvE;AAAA;AAAA,EAEA,SAAwB,CAAC;AAAA;AAAA,EAEzB,SAA4B;AAAA;AAAA,EA0DpC,SAAS,OAAgC;AACvC,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA,EAGA,WAAmC;AACjC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,QAAuB;AACrB,UAAM,QAAQ,KAAK;AACnB,WAAO,KAAK;AACZ,SAAK,SAAS,CAAC;AACf,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,UAAgB;AACd,SAAK,QAAQ,UAAU,OAAO,KAAK;AAAA,EACrC;AAAA;AAAA,EAGA,GACI,SACA,SACI;AACN,SAAK,UAAU,IAAI,SAAS,OAAO;AACnC,WAAO;AAAA,EACT;AACF;",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import type { Client, Command, MetadataBearer } from '@aws-sdk/types';
+/** A type identifying _any_ AWS {@link Client} */
+type AnyClient = Client<any, any, any>;
+/** A type identifying _any_ AWS {@link Command} */
+type AnyCommand = Command<any, any, any, any, any>;
+/** Infer the _input type_ of an AWS {@link Command} */
+type CommandInput<T> = T extends Command<any, infer Input, any, any, any> ? Input : never;
+/** Infer the _output type_ of an AWS {@link Command} */
+type CommandOutput<T> = T extends Command<any, any, any, infer Output, any> ? Omit<Output, '$metadata'> & Partial<MetadataBearer> : never;
+/** A type identifying a _constructor_ for an instance */
+type Constructor<T> = new (...args: any) => T;
+/** An interface defining a _call record_ in a {@link AWSMock} */
+export interface AWSMockCall {
+    command: string;
+    input: any;
+    success: boolean;
+}
+/** A _handler_ for intercepting commands in {@link AWSMock} */
+export type AWSMockHandler<Input, Output, State = any> = (input: Input, state: State | undefined) => Output | Promise<Output>;
+/** The {@link AWSMock} class allows easy mocking of AWS clients */
+export declare class AWSMock<State = any> {
+    private _client;
+    /** All configured command handlers */
+    private _handlers;
+    /** The _original_ (unmocked) `send(...)` method from the client prototype */
+    private _send;
+    /** Current record of all calls handled by this instance */
+    private _calls;
+    /** Current state to be passed to handlers */
+    private _state;
+    /** Create a new {@link AWSMock} instance mocking the specified {@link Client} */
+    constructor(client: Constructor<AnyClient>);
+    /** Associate a _state_ with this instance, to be passed to handlers */
+    setState(state: State | undefined): void;
+    /** Return the list of calls executed by this instance */
+    getCalls(): readonly AWSMockCall[];
+    /**
+     * Reset this instance by zeroing the {@link AWSMock.calls calls} and wiping
+     * the {@link AWSMock.state state}.
+     *
+     * @returns The list of calls executed by this instance before reset.
+     */
+    reset(): AWSMockCall[];
+    /** Destroy this instance, restoring the mocked methods */
+    destroy(): void;
+    /** Setup a _handler_ for a specific {@link Command} */
+    on<AWSCommand extends AnyCommand>(command: new (...args: any) => AWSCommand, handler: AWSMockHandler<CommandInput<AWSCommand>, CommandOutput<AWSCommand>, State>): this;
+}
+export {};

package/dist/index.mjs

@@ -0,0 +1,82 @@
+// index.ts
+import { randomUUID } from "node:crypto";
+var AWSMock = class {
+  // Overload to hide private parameter
+  constructor(_client) {
+    this._client = _client;
+    this._send = _client.prototype.send;
+    const clientName = _client.name || /* coverage ignore next */
+    "[Unknown Client]";
+    _client.prototype.send = (_command, ..._args) => {
+      const commandProto = Object.getPrototypeOf(_command);
+      const commandConstuctor = commandProto.constructor;
+      const commandName = commandConstuctor?.name || /* coverage ignore next */
+      "[Unknown Command]";
+      const lastArgument = _args.pop();
+      const cb = typeof lastArgument === "function" ? lastArgument : void 0;
+      const promise = Promise.resolve().then(async () => {
+        const handler = this._handlers.get(commandConstuctor);
+        if (!handler)
+          throw new Error(`No mock for "${clientName}.${commandName}"`);
+        const result = await handler(_command.input, this._state);
+        if (!result)
+          throw new Error(`Mock for "${clientName}.${commandName}" returned no result`);
+        if (!result.$metadata)
+          result.$metadata = { httpStatusCode: 200 };
+        if (!result.$metadata.requestId)
+          result.$metadata.requestId = randomUUID();
+        return result;
+      }).then((result) => {
+        this._calls.push({ command: commandName, input: _command.input, success: true });
+        return result;
+      }, (error) => {
+        this._calls.push({ command: commandName, input: _command.input, success: false });
+        throw error;
+      });
+      if (cb)
+        promise.then((result) => cb(null, result), (error) => cb(error));
+      return promise;
+    };
+  }
+  /** All configured command handlers */
+  _handlers = /* @__PURE__ */ new Map();
+  /** The _original_ (unmocked) `send(...)` method from the client prototype */
+  _send;
+  /** Current record of all calls handled by this instance */
+  _calls = [];
+  /** Current state to be passed to handlers */
+  _state = void 0;
+  /** Associate a _state_ with this instance, to be passed to handlers */
+  setState(state) {
+    this._state = state;
+  }
+  /** Return the list of calls executed by this instance */
+  getCalls() {
+    return this._calls;
+  }
+  /**
+   * Reset this instance by zeroing the {@link AWSMock.calls calls} and wiping
+   * the {@link AWSMock.state state}.
+   *
+   * @returns The list of calls executed by this instance before reset.
+   */
+  reset() {
+    const calls = this._calls;
+    delete this._state;
+    this._calls = [];
+    return calls;
+  }
+  /** Destroy this instance, restoring the mocked methods */
+  destroy() {
+    this._client.prototype.send = this._send;
+  }
+  /** Setup a _handler_ for a specific {@link Command} */
+  on(command, handler) {
+    this._handlers.set(command, handler);
+    return this;
+  }
+};
+export {
+  AWSMock
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";AAAA,SAAS,kBAAkB;AAmCpB,IAAM,UAAN,MAA2B;AAAA;AAAA,EAahC,YAAoB,SAAiC;AAAjC;AAElB,SAAK,QAAQ,QAAQ,UAAU;AAG/B,UAAM,aAAa,QAAQ;AAAA,IAAmC;AAG9D,YAAQ,UAAU,OAAO,CAAC,aAAyB,UAA+B;AAChF,YAAM,eAAe,OAAO,eAAe,QAAQ;AACnD,YAAM,oBAAoB,aAAa;AACvC,YAAM,cAAc,mBAAmB;AAAA,MAAmC;AAG1E,YAAM,eAAe,MAAM,IAAI;AAC/B,YAAM,KACJ,OAAO,iBAAiB,aAAa,eAAe;AAGtD,YAAM,UAAU,QAAQ,QAAQ,EAAE,KAAK,YAAY;AAEjD,cAAM,UAAU,KAAK,UAAU,IAAI,iBAAiB;AACpD,YAAI,CAAE;AAAS,gBAAM,IAAI,MAAM,gBAAgB,cAAc,cAAc;AAG3E,cAAM,SAAyB,MAAM,QAAQ,SAAS,OAAO,KAAK,MAAM;AAGxE,YAAI,CAAE;AAAQ,gBAAM,IAAI,MAAM,aAAa,cAAc,iCAAiC;AAG1F,YAAI,CAAE,OAAO;AAAW,iBAAO,YAAY,EAAE,gBAAgB,IAAI;AACjE,YAAI,CAAE,OAAO,UAAU;AAAW,iBAAO,UAAU,YAAY,WAAW;AAG1E,eAAO;AAAA,MACT,CAAC,EAAE,KAAK,CAAC,WAAW;AAElB,aAAK,OAAO,KAAK,EAAE,SAAS,aAAa,OAAO,SAAS,OAAO,SAAS,KAAK,CAAC;AAC/E,eAAO;AAAA,MACT,GAAG,CAAC,UAAU;AAEZ,aAAK,OAAO,KAAK,EAAE,SAAS,aAAa,OAAO,SAAS,OAAO,SAAS,MAAM,CAAC;AAChF,cAAM;AAAA,MACR,CAAC;AAGD,UAAI;AAAI,gBAAQ,KAAK,CAAC,WAAW,GAAG,MAAM,MAAM,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC;AACvE,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA,EA7DQ,YAAY,oBAAI,IAAuD;AAAA;AAAA,EAEvE;AAAA;AAAA,EAEA,SAAwB,CAAC;AAAA;AAAA,EAEzB,SAA4B;AAAA;AAAA,EA0DpC,SAAS,OAAgC;AACvC,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA,EAGA,WAAmC;AACjC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,QAAuB;AACrB,UAAM,QAAQ,KAAK;AACnB,WAAO,KAAK;AACZ,SAAK,SAAS,CAAC;AACf,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,UAAgB;AACd,SAAK,QAAQ,UAAU,OAAO,KAAK;AAAA,EACrC;AAAA;AAAA,EAGA,GACI,SACA,SACI;AACN,SAAK,UAAU,IAAI,SAAS,OAAO;AACnC,WAAO;AAAA,EACT;AACF;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@juit/lib-aws-mock",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Easy Mocking for AWS SDK v3",
+  "main": "index.js",
+  "scripts": {
+    "build": "plug",
+    "coverage": "plug coverage",
+    "dev": "plug coverage -w src -w test",
+    "lint": "plug lint",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "transpile": "plug transpile"
+  },
+  "dependencies": {
+    "@aws-sdk/types": "^3.296.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-sts": "^3.297.0",
+    "@plugjs/build": "^0.3.0"
+  },
+  "author": "Juit Developers <developers@juit.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/juitnow/juit-lib-aws-mock.git"
+  },
+  "keywords": [
+    "aws",
+    "aws-sdk",
+    "mock",
+    "testing"
+  ],
+  "bugs": {
+    "url": "https://github.com/juitnow/juit-lib-aws-mock/issues"
+  },
+  "homepage": "https://github.com/juitnow/juit-lib-aws-mock#readme",
+  "files": [
+    "*.md",
+    "dist/",
+    "src/"
+  ],
+  "directories": {
+    "test": "test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto'
+
+import type { Client, Command, MetadataBearer } from '@aws-sdk/types'
+
+/** A type identifying _any_ AWS {@link Client} */
+type AnyClient = Client<any, any, any>
+
+/** A type identifying _any_ AWS {@link Command} */
+type AnyCommand = Command<any, any, any, any, any>
+
+/** Infer the _input type_ of an AWS {@link Command} */
+type CommandInput<T> =
+  T extends Command<any, infer Input, any, any, any> ? Input : never
+
+/** Infer the _output type_ of an AWS {@link Command} */
+type CommandOutput<T> =
+  T extends Command<any, any, any, infer Output, any> ?
+    Omit<Output, '$metadata'> & Partial<MetadataBearer> :
+    never
+
+/** A type identifying a _constructor_ for an instance */
+type Constructor<T> = new (...args: any) => T
+
+/** An interface defining a _call record_ in a {@link AWSMock} */
+export interface AWSMockCall {
+  command: string,
+  input: any,
+  success: boolean,
+}
+
+/** A _handler_ for intercepting commands in {@link AWSMock} */
+export type AWSMockHandler<Input, Output, State = any> =
+  (input: Input, state: State | undefined) => Output | Promise<Output>
+
+/** The {@link AWSMock} class allows easy mocking of AWS clients */
+export class AWSMock<State = any> {
+  /** All configured command handlers */
+  private _handlers = new Map<Constructor<AnyCommand>, AWSMockHandler<any, any>>()
+  /** The _original_ (unmocked) `send(...)` method from the client prototype */
+  private _send: AnyClient['send']
+  /** Current record of all calls handled by this instance */
+  private _calls: AWSMockCall[] = []
+  /** Current state to be passed to handlers */
+  private _state: State | undefined = undefined
+
+  /** Create a new {@link AWSMock} instance mocking the specified {@link Client} */
+  constructor(client: Constructor<AnyClient>)
+  // Overload to hide private parameter
+  constructor(private _client: Constructor<AnyClient>) {
+    // Remember the original `send` method
+    this._send = _client.prototype.send
+
+    // Figure out the name of the client
+    const clientName = _client.name || /* coverage ignore next */ '[Unknown Client]'
+
+    // Inject our `send` method in the client's prototype
+    _client.prototype.send = (_command: AnyCommand, ..._args: any[]): Promise<any> => {
+      const commandProto = Object.getPrototypeOf(_command)
+      const commandConstuctor = commandProto.constructor
+      const commandName = commandConstuctor?.name || /* coverage ignore next */ '[Unknown Command]'
+
+      // Figure out if we have a callback
+      const lastArgument = _args.pop()
+      const cb: ((err: any, data?: any) => void) | undefined =
+        typeof lastArgument === 'function' ? lastArgument : undefined
+
+      // Always work with promises
+      const promise = Promise.resolve().then(async () => {
+        // Get the handler for the method and verify it
+        const handler = this._handlers.get(commandConstuctor)
+        if (! handler) throw new Error(`No mock for "${clientName}.${commandName}"`)
+
+        // Call the handler and get the result
+        const result: MetadataBearer = await handler(_command.input, this._state)
+
+        // If no result (null loose check) then simply return a 404
+        if (! result) throw new Error(`Mock for "${clientName}.${commandName}" returned no result`)
+
+        // If we don't have some metadata, inject some fake stuff
+        if (! result.$metadata) result.$metadata = { httpStatusCode: 200 }
+        if (! result.$metadata.requestId) result.$metadata.requestId = randomUUID()
+
+        // All done!
+        return result
+      }).then((result) => {
+        // On success, record the call and return the result
+        this._calls.push({ command: commandName, input: _command.input, success: true })
+        return result
+      }, (error) => {
+        // On failure, record the call and throw the error
+        this._calls.push({ command: commandName, input: _command.input, success: false })
+        throw error
+      })
+
+      // Invoke our callback (if any) and always return the promise
+      if (cb) promise.then((result) => cb(null, result), (error) => cb(error))
+      return promise
+    }
+  }
+
+  /** Associate a _state_ with this instance, to be passed to handlers */
+  setState(state: State | undefined): void {
+    this._state = state
+  }
+
+  /** Return the list of calls executed by this instance */
+  getCalls(): readonly AWSMockCall[] {
+    return this._calls
+  }
+
+  /**
+   * Reset this instance by zeroing the {@link AWSMock.calls calls} and wiping
+   * the {@link AWSMock.state state}.
+   *
+   * @returns The list of calls executed by this instance before reset.
+   */
+  reset(): AWSMockCall[] {
+    const calls = this._calls
+    delete this._state
+    this._calls = []
+    return calls
+  }
+
+  /** Destroy this instance, restoring the mocked methods */
+  destroy(): void {
+    this._client.prototype.send = this._send
+  }
+
+  /** Setup a _handler_ for a specific {@link Command} */
+  on<AWSCommand extends AnyCommand>(
+      command: new (...args: any) => AWSCommand,
+      handler: AWSMockHandler<CommandInput<AWSCommand>, CommandOutput<AWSCommand>, State>,
+  ): this {
+    this._handlers.set(command, handler)
+    return this
+  }
+}