Merge pull request #2215 from hey-api/refactor/plugin-walk

refactor(parser): replace plugin.subscribe with plugin.walk

Author: mrlubos

.changeset/lucky-bees-exist.md

@@ -0,0 +1,15 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+feat(parser): replace `plugin.subscribe()` with `plugin.forEach()`
+
+### Added `plugin.forEach()` method
+
+This method replaces the `.subscribe()` method. Additionally, `.forEach()` is executed immediately, which means we don't need the `before` and `after` events – simply move your code before and after the `.forEach()` block.
+
+```ts
+plugin.forEach('operation', 'schema', (event) => {
+  // do something with event
+});
+```

docs/openapi-ts/migrating.md

@@ -27,6 +27,22 @@ This config option is deprecated and will be removed in favor of [clients](./cli
 
 This config option is deprecated and will be removed.
 
+## v0.75.0
+
+### Added `plugin.forEach()` method
+
+This method replaces the `.subscribe()` method. Additionally, `.forEach()` is executed immediately, which means we don't need the `before` and `after` events – simply move your code before and after the `.forEach()` block.
+
+```ts
+plugin.subscribe('operation', (event) => { // [!code --]
+  // do something with event // [!code --]
+}); // [!code --]
+plugin.subscribe('schema', (event) => { // [!code --]
+plugin.forEach('operation', 'schema', (event) => { // [!code ++]
+  // do something with event
+});
+```
+
 ## v0.74.0
 
 ### Single Zod schema per request

docs/openapi-ts/plugins/custom.md

@@ -118,20 +118,12 @@ export const handler: Plugin.Handler<Config> = ({ plugin }) => {
     path: plugin.output,
   });
 
-  plugin.subscribe('before', () => {
-    // do something before parsing the input
-  });
-
-  plugin.subscribe('operation', ({ operation }) => {
-    // do something with the operation model
-  });
-
-  plugin.subscribe('schema', ({ operation }) => {
-    // do something with the schema model
-  });
-
-  plugin.subscribe('after', () => {
-    // do something after parsing the input
+  plugin.forEach('operation', 'schema', (event) => {
+    if (event.type === 'operation') {
+      // do something with the operation model
+    } else if (event.type === 'schema') {
+      // do something with the schema model
+    }
   });
 
   // we're using the TypeScript Compiler API

packages/openapi-ts-tests/test/openapi-ts.config.ts

@@ -57,8 +57,8 @@ export default defineConfig(() => {
       //   'invalid',
       //   'servers-entry.yaml',
       // ),
-      path: path.resolve(__dirname, 'spec', '3.1.x', 'validators.yaml'),
-      // path: path.resolve(__dirname, 'spec', 'v3-transforms.json'),
+      // path: path.resolve(__dirname, 'spec', '3.1.x', 'validators.yaml'),
+      path: path.resolve(__dirname, 'spec', 'v3-transforms.json'),
       // path: 'http://localhost:4000/',
       // path: 'https://get.heyapi.dev/',
       // path: 'https://get.heyapi.dev/hey-api/backend?branch=main&version=1.0.0',
@@ -93,9 +93,9 @@ export default defineConfig(() => {
       // ),
     },
     plugins: [
-      customClientPlugin({
-        baseUrl: false,
-      }),
+      // customClientPlugin({
+      //   baseUrl: false,
+      // }),
       // myClientPlugin(),
       {
         // baseUrl: false,
@@ -123,13 +123,13 @@ export default defineConfig(() => {
         // responseStyle: 'data',
         // throwOnError: true,
         // transformer: '@hey-api/transformers',
-        // transformer: true,
+        transformer: true,
         validator: 'zod',
       },
       {
         // bigInt: true,
-        dates: true,
-        // name: '@hey-api/transformers',
+        // dates: true,
+        name: '@hey-api/transformers',
       },
       {
         enums: 'typescript+namespace',

packages/openapi-ts/src/generate/output.ts

@@ -3,7 +3,6 @@ import path from 'node:path';
 import ts from 'typescript';
 
 import { compiler } from '../compiler';
-import { parseIR } from '../ir/parser';
 import type { IR } from '../ir/types';
 import { getClientPlugin } from '../plugins/@hey-api/client-core/utils';
 import { generateClientBundle } from './client';
@@ -33,11 +32,9 @@ export const generateOutput = async ({ context }: { context: IR.Context }) => {
   }
 
   for (const plugin of context.registerPlugins()) {
-    plugin.run();
+    await plugin.run();
   }
 
-  await parseIR({ context });
-
   if (!context.config.dryRun) {
     const indexFile = context.createFile({
       id: '_index',

packages/openapi-ts/src/ir/context.ts

@@ -1,6 +1,5 @@
 import path from 'node:path';
 
-import { HeyApiError } from '../error';
 import { TypeScriptFile } from '../generate/files';
 import { PluginInstance } from '../plugins/shared/utils/instance';
 import type { Config, StringCase } from '../types/config';
@@ -42,47 +41,6 @@ export interface ContextFile {
   path: string;
 }
 
-export interface Events {
-  /**
-   * Called after parsing.
-   */
-  after: () => void;
-  /**
-   * Called before parsing.
-   */
-  before: () => void;
-  operation: (args: {
-    method: keyof IR.PathItemObject;
-    operation: IR.OperationObject;
-    path: string;
-  }) => void;
-  parameter: (args: {
-    $ref: string;
-    name: string;
-    parameter: IR.ParameterObject;
-  }) => void;
-  requestBody: (args: {
-    $ref: string;
-    name: string;
-    requestBody: IR.RequestBodyObject;
-  }) => void;
-  schema: (args: {
-    $ref: string;
-    name: string;
-    schema: IR.SchemaObject;
-  }) => void;
-  server: (args: { server: IR.ServerObject }) => void;
-}
-
-type ListenerWithMeta<T extends keyof Events> = {
-  callbackFn: Events[T];
-  pluginName: string;
-};
-
-type Listeners = {
-  [T in keyof Events]?: Array<ListenerWithMeta<T>>;
-};
-
 export class IRContext<Spec extends Record<string, any> = any> {
   /**
    * Configuration for parsing and generating the output. This
@@ -92,11 +50,11 @@ export class IRContext<Spec extends Record<string, any> = any> {
   /**
    * A map of files that will be generated from `spec`.
    */
-  public files: Files;
+  public files: Files = {};
   /**
    * Intermediate representation model obtained from `spec`.
    */
-  public ir: IR.Model;
+  public ir: IR.Model = {};
   /**
    * A map of registered plugin instances, keyed by plugin name. Plugins are
    * registered through the `registerPlugin` method and can be accessed by
@@ -108,50 +66,11 @@ export class IRContext<Spec extends Record<string, any> = any> {
    */
   public spec: Spec;
 
-  /**
-   * A map of event listeners.
-   */
-  private listeners: Listeners;
-
   constructor({ config, spec }: { config: Config; spec: Spec }) {
     this.config = config;
-    this.files = {};
-    this.ir = {};
-    this.listeners = {};
     this.spec = spec;
   }
 
-  /**
-   * Notify all event listeners about `event`.
-   */
-  public async broadcast<T extends keyof Events>(
-    event: T,
-    ...args: Parameters<Events[T]>
-  ): Promise<void> {
-    const eventListeners = this.listeners[event];
-
-    if (eventListeners) {
-      for (const listener of eventListeners) {
-        try {
-          await listener.callbackFn(
-            // @ts-expect-error
-            ...args,
-          );
-        } catch (error) {
-          const originalError =
-            error instanceof Error ? error : new Error(String(error));
-          throw new HeyApiError({
-            args,
-            error: originalError,
-            event,
-            name: 'BroadcastError',
-            pluginName: listener.pluginName,
-          });
-        }
-      }
-    }
-  }
-
   /**
    * Create and return a new TypeScript file. Also set the current file context
    * to the newly created file.
@@ -216,13 +135,14 @@ export class IRContext<Spec extends Record<string, any> = any> {
   }
 
   /**
-   * Generator that iterates through plugin order and registers each plugin.
-   * Yields the registered plugin instance for each plugin name.
+   * Registers all plugins in the order specified by the configuration and returns
+   * an array of the registered PluginInstance objects. Each plugin is instantiated
+   * and added to the context's plugins map.
+   *
+   * @returns {ReadonlyArray<PluginInstance>} An array of registered plugin instances in order.
    */
-  public *registerPlugins(): Generator<PluginInstance> {
-    for (const name of this.config.pluginOrder) {
-      yield this.registerPlugin(name);
-    }
+  public registerPlugins(): ReadonlyArray<PluginInstance> {
+    return this.config.pluginOrder.map((name) => this.registerPlugin(name));
   }
 
   // TODO: parser - works the same as resolveRef, but for IR schemas.
@@ -245,21 +165,4 @@ export class IRContext<Spec extends Record<string, any> = any> {
       spec: this.spec,
     });
   }
-
-  /**
-   * Register a new `event` listener.
-   */
-  public subscribe<T extends keyof Events>(
-    event: T,
-    callbackFn: Events[T],
-    pluginName: string,
-  ): void {
-    if (!this.listeners[event]) {
-      this.listeners[event] = [];
-    }
-    this.listeners[event].push({
-      callbackFn,
-      pluginName: pluginName ?? '',
-    });
-  }
 }

packages/openapi-ts/src/ir/parser.ts

@@ -3,7 +3,7 @@ import type {
   SecuritySchemeObject,
   ServerObject,
 } from '../openApi/3.1.x/types/spec';
-import type { ContextFile as CtxFile, Events, IRContext } from './context';
+import type { ContextFile as CtxFile, IRContext } from './context';
 import type { IRMediaType } from './mediaType';
 
 interface IRBodyObject {
@@ -217,7 +217,6 @@ export namespace IR {
   export type BodyObject = IRBodyObject;
   export type ComponentsObject = IRComponentsObject;
   export type Context<Spec extends Record<string, any> = any> = IRContext<Spec>;
-  export type ContextEvents = Events;
   export type ContextFile = CtxFile;
   export type Model = IRModel;
   export type OperationObject = IROperationObject;