[IDP-1768] Add experimental MSW plugin (#23)

* [IDP-1768] Add unstable MSW plugin

* Add docs

* Update docs, rename to experimental

* update debug

* PR comments

* fix broken test

.changeset/dull-cougars-call.md

@@ -0,0 +1,5 @@
+---
+"@workleap/create-schemas": minor
+---
+
+Add `experimental_openapiMSWPlugin`

.changeset/new-bears-sleep.md

@@ -0,0 +1,5 @@
+---
+"@workleap/create-schemas": minor
+---
+
+[BREAKING] Rename `openapiFetchPlugin` to `experimental_openapiFetchPlugin`

debug/create-schemas.config.ts

@@ -1,8 +1,8 @@
 import { defineConfig } from "@workleap/create-schemas";
-import { openapiFetchPlugin } from "@workleap/create-schemas/plugins";
+import { experimental_openapiFetchPlugin, experimental_openapiMSWPlugin } from "@workleap/create-schemas/plugins";
 
 export default defineConfig({
     input: "v1.yaml",
     outdir: "src/codegen/v1",
-    plugins: [openapiFetchPlugin()]
+    plugins: [experimental_openapiFetchPlugin(), experimental_openapiMSWPlugin()]
 });

debug/package.json

@@ -7,6 +7,7 @@
   },
   "dependencies": {
     "@workleap/create-schemas": "workspace:*",
-    "openapi-fetch": "^0.10.2"
+    "openapi-fetch": "0.10.2",
+    "openapi-msw": "0.7.0"
   }
 }

debug/src/codegen/v1/client.ts

@@ -1,4 +1,4 @@
-/** Do not modify. This file has been generated by @workleap/create-schemas */
+/** This file has been generated by @workleap/create-schemas (https://github.com/gsoft-inc/wl-openapi-typescript). Do not modify manually. */
 import type { paths } from "./types.ts";
 import _createClient from "openapi-fetch";
 

debug/src/codegen/v1/openapi-msw.ts

@@ -0,0 +1,5 @@
+/** This file has been generated by @workleap/create-schemas (https://github.com/gsoft-inc/wl-openapi-typescript). Do not modify manually. */
+import type { paths } from "./types.ts";
+import { createOpenApiHttp } from "openapi-msw";
+
+export const http = createOpenApiHttp<paths>();

debug/src/codegen/v1/types.ts

@@ -1,4 +1,4 @@
-/** Do not modify. This file has been generated by @workleap/create-schemas */
+/** This file has been generated by @workleap/create-schemas (https://github.com/gsoft-inc/wl-openapi-typescript). Do not modify manually. */
 export interface paths {
     "/good-vibes-points/{userId}": {
         parameters: {

docs/src/msw.md

@@ -6,6 +6,52 @@ order: -6
 
 # Mock Service Worker
 
+## Type-safe Handlers
+
+The [`experimental_openapiMSWPlugin` plugin](/using-plugins/#experimental_openapimswplugin) allows you to define MSW handlers in a type-safe way.
+
+To use this client, you need to install the [`openapi-msw`](https://www.npmjs.com/package/openapi-msw) package:
+
++++ pnpm
+```bash
+pnpm add openapi-msw
+```
++++ npm
+```bash
+npm install openapi-msw
+```
++++ yarn
+```bash
+yarn add openapi-msw
+```
++++
+
+**Example usage:**
+
+```ts #2,5 create-schemas.config.ts 
+import { defineConfig } from "@workleap/create-schemas";
+import { experimental_openapiMSWPlugin } from "@workleap/create-schemas/plugins";
+
+export default defineConfig({
+    plugins: [experimental_openapiMSWPlugin()]
+    input: "v1.yaml",
+    outdir: "codegen",
+});
+```
+
+```ts #5-6
+import { http } from "./codegen/openapi-msw.ts";
+
+export const handlers = [
+    http.get("/good-vibes-points/{userId}", ({ response }) => {
+        return response(200).json({ pointx: 50 });
+                                 // ^^^^^^ Property "pointx" does not exist on type { points: number }
+    }),
+];
+```
+
+## Auto-generated handlers
+
 *Soon...*
 
 See https://source.mswjs.io/

docs/src/using-plugins.md

@@ -27,7 +27,7 @@ export default defineConfig({
 
 ## Built-in Plugins
 
-### `openapiFetchPlugin`
+### `experimental_openapiFetchPlugin`
 
 **Description:**
 
@@ -53,10 +53,10 @@ yarn add openapi-fetch
 
 ```ts #2,5 create-schemas.config.ts 
 import { defineConfig } from "@workleap/create-schemas";
-import { openapiFetchPlugin } from "@workleap/create-schemas/plugins";
+import { experimental_openapiFetchPlugin } from "@workleap/create-schemas/plugins";
 
 export default defineConfig({
-    plugins: [openapiFetchPlugin()]
+    plugins: [experimental_openapiFetchPlugin()]
     input: "v1.yaml",
     outdir: "codegen",
 });
@@ -80,6 +80,58 @@ if (data?.point) {
 }
 ```
 
+### `experimental_openapiMSWPlugin`
+
+!!!warning Warning
+
+This plugin is currently marked as **experimental**. It may change at any time.
+
+!!!
+
+**Description:**
+
+This plugins outputs a very thin wrapper over [openapi-msw](https://www.npmjs.com/package/openapi-msw). This package lets your define typed MSW handlers.
+
+To use this client, you need to install the `openapi-msw` package:
+
++++ pnpm
+```bash
+pnpm add openapi-msw
+```
++++ npm
+```bash
+npm install openapi-msw
+```
++++ yarn
+```bash
+yarn add openapi-msw
+```
++++
+
+**Example usage:**
+
+```ts #2,5 create-schemas.config.ts 
+import { defineConfig } from "@workleap/create-schemas";
+import { experimental_openapiMSWPlugin } from "@workleap/create-schemas/plugins";
+
+export default defineConfig({
+    plugins: [experimental_openapiMSWPlugin()]
+    input: "v1.yaml",
+    outdir: "codegen",
+});
+```
+
+```ts #5-6
+import { http } from "./codegen/openapi-msw.ts";
+
+export const handlers = [
+    http.get("/good-vibes-points/{userId}", ({ response }) => {
+        return response(200).json({ pointx: 50 });
+                                 // ^^^^^^ Property "pointx" does not exist on type { points: number }
+    }),
+];
+```
+
 
 ## Creating a Plugin
 
@@ -122,7 +174,7 @@ export default defineConfig({
 });
 ```
 
-## Build hooks
+### Build hooks
 
 To interact with the code generation process, a plugin may include "hooks". Hooks are function that are are called at various stages of the generation. Hooks can affect how a build is run, add a file to the output, or modify a build once complete.
 

packages/create-schemas/src/plugins/index.ts

@@ -1,2 +1,3 @@
 export type { Plugin } from "./plugin.ts";
-export { openapiFetchPlugin } from "./openapi-fetch-plugin.ts";
+export { experimental_openapiFetchPlugin } from "./openapi-fetch-plugin.ts";
+export { experimental_openapiMSWPlugin } from "./openapi-msw-plugin.ts";

packages/create-schemas/src/plugins/openapi-fetch-plugin.ts

@@ -2,7 +2,7 @@ import type { Plugin } from "./plugin.ts";
 import { getRelativeModuleResolutionExtension } from "../utils.ts";
 import { openapiTypeScriptId } from "./openapi-typescript-plugin.ts";
 
-export function openapiFetchPlugin(): Plugin {
+export function experimental_openapiFetchPlugin(): Plugin {
     return {
         name: "openapi-fetch-plugin",
         async transform({ id, emitFile }) {
@@ -16,7 +16,7 @@ export function openapiFetchPlugin(): Plugin {
                 filename: "client.ts",
                 code: [
                     `import type { paths } from "./types${importsFileExtension}";`,
-                    "import _createClient from \"openapi-fetch\";",
+                    "import _createClient from \"openapi-fetch\";\n",
                     "export const createClient = _createClient as typeof _createClient<paths, \"application/json\">;"
                 ].join("\n")
             });

packages/create-schemas/src/plugins/openapi-msw-plugin.ts

@@ -0,0 +1,25 @@
+import { getRelativeModuleResolutionExtension } from "../utils.ts";
+import { openapiTypeScriptId } from "./openapi-typescript-plugin.ts";
+import type { Plugin } from "./plugin.ts";
+
+export function experimental_openapiMSWPlugin(): Plugin {
+    return {
+        name: "openapi-msw-plugin",
+        async transform({ id, emitFile }) {
+            if (id !== openapiTypeScriptId) {
+                return;
+            }
+
+            const importsFileExtension = getRelativeModuleResolutionExtension();
+
+            emitFile({
+                filename: "openapi-msw.ts",
+                code: [
+                    `import type { paths } from "./types${importsFileExtension}";`,
+                    "import { createOpenApiHttp } from \"openapi-msw\";\n",
+                    "export const http = createOpenApiHttp<paths>();"
+                ].join("\n")
+            });
+        }
+    };
+}

packages/create-schemas/tests/e2e.test.ts

@@ -104,9 +104,9 @@ describe.concurrent("e2e", () => {
             const tempFolder = await createTemporaryFolder({ onTestFinished: onTestFinished });
 
             const configFile = `
-            import { openapiFetchPlugin } from "../../../src/plugins";
+            import { experimental_openapiFetchPlugin } from "../../../src/plugins";
             
-            export default { plugins: [openapiFetchPlugin()] };
+            export default { plugins: [experimental_openapiFetchPlugin()] };
             `;
 
             await writeFile(join(tempFolder, "create-schemas.config.ts"), configFile);

packages/create-schemas/tests/generate.test.ts

@@ -4,7 +4,7 @@ import { resolveConfig } from "../src/config.ts";
 import { join } from "path";
 import { dataFolder } from "./fixtures.ts";
 import { openapiTypeScriptFilename } from "../src/plugins/openapi-typescript-plugin.ts";
-import { openapiFetchPlugin } from "../src/plugins/openapi-fetch-plugin.ts";
+import { experimental_openapiFetchPlugin } from "../src/plugins/openapi-fetch-plugin.ts";
 
 describe.concurrent("generate", () => {
     test("sanitize names", async ({ expect }) => {
@@ -46,7 +46,7 @@ describe.concurrent("generate", () => {
     test("generate client", async ({ expect }) => {
         const { files } = await generate(await resolveConfig({
             input: join(dataFolder, "todo.json"),
-            plugins: [openapiFetchPlugin()]
+            plugins: [experimental_openapiFetchPlugin()]
         }));
 
         const clientFile = files.find(file => file.filename === "client.ts");

packages/create-schemas/tests/plugins.test.ts

@@ -1,12 +1,14 @@
 
-import { assert, describe, expect, test } from "vitest";
+import { assert, describe, test } from "vitest";
 import { headerPlugin } from "../src/plugins/header-plugin.ts";
 import { typesPlugin } from "../src/plugins/types-plugin.ts";
 import { openapiTypeScriptId, openapiTypeScriptFilename } from "../src/plugins/openapi-typescript-plugin.ts";
 import { resolveConfig } from "../src/config.ts";
+import { experimental_openapiMSWPlugin } from "../src/plugins/openapi-msw-plugin.ts";
+import { experimental_openapiFetchPlugin } from "../src/plugins/openapi-fetch-plugin.ts";
 
 describe.concurrent("plugins", () => {
-    test("headerPlugin", async() => {
+    test("headerPlugin", async({ expect }) => {
         const plugin = headerPlugin({ header: "This is a header" });
 
         assert(plugin.transform);
@@ -27,7 +29,7 @@ describe.concurrent("plugins", () => {
         `);
     });
 
-    test("typesPlugin", async() => {
+    test("typesPlugin", async ({ expect }) => {
         const plugin = typesPlugin();
 
         assert(plugin.transform);
@@ -69,4 +71,82 @@ describe.concurrent("plugins", () => {
           "
         `);
     });
+
+    test("openapiFetchPlugin generates a file when openapi typescript file generated", async ({ expect }) => {
+        const plugin = experimental_openapiFetchPlugin();
+
+        assert(plugin.transform);
+
+        let emittedFile: { filename: string; code: string } | undefined;
+        function emitFile(file: { filename: string; code: string }) {
+            emittedFile = file;
+        }
+
+        await plugin.transform({
+            config: await resolveConfig({ input: "openapi.json" }),
+            id: openapiTypeScriptId,
+            code: "export interface paths {}",
+            filename: openapiTypeScriptFilename,
+            emitFile
+        });
+
+        assert(emittedFile);
+
+        expect(emittedFile.filename).toBe("client.ts");
+        expect(emittedFile.code).toMatchInlineSnapshot(`
+          "import type { paths } from "./types.ts";
+          import _createClient from "openapi-fetch";
+
+          export const createClient = _createClient as typeof _createClient<paths, "application/json">;"
+        `);
+    });
+
+    test("openapiMSWPlugin generates a file when openapi typescript file generated", async ({ expect }) => {
+        const plugin = experimental_openapiMSWPlugin();
+
+        assert(plugin.transform);
+
+        let emittedFile: { filename: string; code: string } | undefined;
+        function emitFile(file: { filename: string; code: string }) {
+            emittedFile = file;
+        }
+
+        await plugin.transform({
+            config: await resolveConfig({ input: "openapi.json" }),
+            id: openapiTypeScriptId,
+            code: "export interface paths {}",
+            filename: openapiTypeScriptFilename,
+            emitFile
+        });
+
+        assert(emittedFile);
+
+        expect(emittedFile.filename).toBe("openapi-msw.ts");
+        expect(emittedFile.code).toMatchInlineSnapshot(`
+          "import type { paths } from "./types.ts";
+          import { createOpenApiHttp } from "openapi-msw";
+
+          export const http = createOpenApiHttp<paths>();"
+        `);
+    });
+
+    test("openapiMSWPlugin doesn't generates a file when openapi typescript file missing", async ({ expect }) => {
+        const plugin = experimental_openapiMSWPlugin();
+
+        assert(plugin.transform);
+
+        let emittedFile: { filename: string; code: string } | undefined;
+        function emitFile(file: { filename: string; code: string }) {
+            emittedFile = file;
+        }
+
+        await plugin.transform({
+            config: await resolveConfig({ input: "openapi.json" }),
+            code: "export interface paths {}",
+            filename: openapiTypeScriptFilename,
+            emitFile
+        });
+
+        expect(emittedFile).toBeUndefined();
+    });
 });