From 8f94272e19b12da0019f57686fb942a3c566747c Mon Sep 17 00:00:00 2001
From: Anthony Brown <121869075+anthony-nhs@users.noreply.github.com>
Date: Mon, 20 Nov 2023 15:51:20 +0000
Subject: [PATCH] update typescript and testing documentation

---
 website/docs/intro/06-testing.md    | 37 +++++++++++++++++++++++++++++
 website/docs/intro/06-typescript.md | 28 ++++++++++++++++++++++
 2 files changed, 65 insertions(+)

diff --git a/website/docs/intro/06-testing.md b/website/docs/intro/06-testing.md
index 2018b942b..603e7a510 100644
--- a/website/docs/intro/06-testing.md
+++ b/website/docs/intro/06-testing.md
@@ -33,3 +33,40 @@ An example of a message generated by Jest unit tests and which signals the need
 ```
 A worker process has failed to exit gracefully and has been force exited. This is likely caused by tests leaking due to improper teardown. Try running with --detectOpenHandles to find leaks. Active timers can also cause this, ensure that .unref() was called on them.
 ```
+
+## jest and typescript
+If you use middy v5+, jest and typescript, and use ts-jest as a transformer, then you need to ensure that middy modules are not transformed. Use this in your jest.config.ts file
+```
+const esModules = ["@middy"].join("|")
+const jestConfig: JestConfigWithTsJest = {
+  ...
+  transform: {
+    "^.+\\.ts?$": [
+      "ts-jest",
+      {
+        useESM: true
+      }
+    ]
+  },
+  transformIgnorePatterns: [`node_modules/(?!${esModules})`],
+  ...
+}
+
+export default jestConfig
+
+``` 
+You must also use the flag `--experimental-vm-modules` when running jest - eg have this in your package.json file
+```
+{
+  ...
+  "scripts": {
+    ...
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    ...
+  },
+  ...
+}
+
+``` 
+
+See https://kulshekhar.github.io/ts-jest/docs/guides/esm-support/ and https://jestjs.io/docs/ecmascript-modules for more details
diff --git a/website/docs/intro/06-typescript.md b/website/docs/intro/06-typescript.md
index 5d6ead39e..fadbfc20d 100644
--- a/website/docs/intro/06-typescript.md
+++ b/website/docs/intro/06-typescript.md
@@ -43,3 +43,31 @@ Note that when using TypeScript, you should use what we call the _Middleware-fir
 This approach makes sure that, as you attach middlewares, the type system understands how the `event` and the `context` arguments are augmented by the various middlewares and inside your handler code you can have a nice type-checking and auto-completion experience.
 
 You can also [write custom middlewares with TypeScript](/docs/writing-middlewares/intro).
+
+This is an example tsconfig.json file that can be used for typescript projects
+
+```
+{
+  "compilerOptions": {
+    "incremental": true,
+    "target": "es2020",
+    "module": "es2020",
+    "declaration": true,
+    "sourceMap": true,
+    "composite": true,
+    "strict": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "preserveConstEnums": true,
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "rootDir": ".",
+    "outDir": "lib"
+  }
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules"]
+}
+
+```