feat: Add bulk callback support for patch.operations

- Update type definition to support both Record and bulk callback function
- Implement bulk callback iteration for OpenAPI v2 and v3
- Add comprehensive tests for bulk callback functionality
- Support async operations for both patterns
- All tests passing (61/61)

Co-authored-by: mrlubos <[e-mail]>

packages/shared/src/config/parser/patch.ts

···
         meta: OpenApiMetaObject.V2_0_X | OpenApiMetaObject.V3_0_X | OpenApiMetaObject.V3_1_X,
       ) => void;
       /**
-       * Patch OpenAPI operations in place. The key is the operation method and operation path, and the function receives the operation object to modify directly.
+       * Patch OpenAPI operations in place. Each function receives the operation
+       * object to be modified in place. Common use cases include injecting
+       * `operationId` for specs that don't have them, adding `x-*` extensions,
+       * setting `deprecated` based on path patterns, or injecting `security`
+       * requirements globally.
+       *
+       * Can be:
+       * - `Record<string, fn>`: Patch specific operations by `"METHOD /path"` key
+       * - `function`: Bulk callback receives `(method, path, operation)` for every operation
+       *
+       * Both patterns support async functions for operations like fetching data
+       * from external sources or performing I/O.
        *
        * @example
+       * ```js
+       * // Named operations
        * operations: {
        *   'GET /foo': (operation) => {
-       *     operation.responses['200'].description = 'foo';
+       *     operation.responses['200'].description = 'Success';
+       *   },
+       *   'POST /bar': (operation) => {
+       *     operation.deprecated = true;
        *   }
        * }
+       *
+       * // Bulk callback for all operations
+       * operations: (method, path, operation) => {
+       *   if (!operation.operationId) {
+       *     operation.operationId = method + buildOperationName(path);
+       *   }
+       * }
+       *
+       * // Async example - inject operationId based on path patterns
+       * operations: async (method, path, operation) => {
+       *   if (operation.operationId) return;
+       *
+       *   const segments = path.split('/').filter(Boolean);
+       *   const parts = segments
+       *     .map((seg) => seg.startsWith('{') ? 'ById' : seg)
+       *     .join('');
+       *   operation.operationId = method + parts;
+       * }
+       * ```
        */
-      operations?: Record<
-        string,
-        (
-          operation:
-            | OpenApiOperationObject.V2_0_X
-            | OpenApiOperationObject.V3_0_X
-            | OpenApiOperationObject.V3_1_X,
-        ) => void
-      >;
+      operations?:
+        | Record<
+            string,
+            (
+              operation:
+                | OpenApiOperationObject.V2_0_X
+                | OpenApiOperationObject.V3_0_X
+                | OpenApiOperationObject.V3_1_X,
+            ) => void | Promise<void>
+          >
+        | ((
+            method: string,
+            path: string,
+            operation:
+              | OpenApiOperationObject.V2_0_X
+              | OpenApiOperationObject.V3_0_X
+              | OpenApiOperationObject.V3_1_X,
+          ) => void | Promise<void>);
       /**
        * Patch OpenAPI parameters in place. The key is the parameter name, and the function receives the parameter object to modify directly.
        *

packages/shared/src/openApi/shared/utils/__tests__/patch.test.ts

···
       });
     });
   });
+
+  describe('patch.operations', () => {
+    describe('OpenAPI v3', () => {
+      it('bulk callback mutates all operations', async () => {
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+              put: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: (method, path, operation) => {
+              operation.operationId = `${method}_${path.replace(/\//g, '_')}`;
+            },
+          },
+          spec,
+        });
+
+        expect(spec.paths!['/foo']?.get?.operationId).toBe('get__foo');
+        expect(spec.paths!['/foo']?.put?.operationId).toBe('put__foo');
+        expect(spec.paths!['/bar']?.post?.operationId).toBe('post__bar');
+      });
+
+      it('bulk callback receives correct parameters', async () => {
+        const fn = vi.fn();
+
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: fn,
+          },
+          spec,
+        });
+
+        expect(fn).toHaveBeenCalledTimes(2);
+        expect(fn).toHaveBeenCalledWith('get', '/foo', spec.paths!['/foo']?.get);
+        expect(fn).toHaveBeenCalledWith('post', '/bar', spec.paths!['/bar']?.post);
+      });
+
+      it('bulk callback can inject operationId based on path patterns', async () => {
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+          paths: {
+            '/users': {
+              get: {
+                responses: {},
+              } as any,
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/users/{id}': {
+              delete: {
+                responses: {},
+              } as any,
+              get: {
+                operationId: 'existingId',
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: (method, path, operation) => {
+              if (operation.operationId) return; // don't override existing
+
+              const segments = path.split('/').filter(Boolean);
+              const parts = segments.map((seg) => (seg.startsWith('{') ? 'ById' : seg)).join('');
+              operation.operationId = method + parts;
+            },
+          },
+          spec,
+        });
+
+        expect(spec.paths!['/users']?.get?.operationId).toBe('getusers');
+        expect(spec.paths!['/users']?.post?.operationId).toBe('postusers');
+        expect(spec.paths!['/users/{id}']?.get?.operationId).toBe('existingId'); // not overridden
+        expect(spec.paths!['/users/{id}']?.delete?.operationId).toBe('deleteusersById');
+      });
+
+      it('bulk callback skips invalid operations', async () => {
+        const fn = vi.fn();
+
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+          paths: {
+            '/bar': {
+              get: null as any,
+              post: 'invalid' as any,
+            },
+            '/baz': 123 as any,
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: fn,
+          },
+          spec,
+        });
+
+        expect(fn).toHaveBeenCalledOnce();
+        expect(fn).toHaveBeenCalledWith('get', '/foo', spec.paths!['/foo']?.get);
+      });
+
+      it('supports async bulk callback', async () => {
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: async (method, path, operation) => {
+              // Simulate async operation
+              await Promise.resolve();
+              operation.operationId = `async_${method}_${path}`;
+            },
+          },
+          spec,
+        });
+
+        expect(spec.paths!['/foo']?.get?.operationId).toBe('async_get_/foo');
+        expect(spec.paths!['/bar']?.post?.operationId).toBe('async_post_/bar');
+      });
+
+      it('supports async Record-based callbacks', async () => {
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: {
+              'GET /foo': async (operation) => {
+                await Promise.resolve();
+                operation.operationId = 'asyncGetFoo';
+              },
+              'POST /bar': async (operation) => {
+                await Promise.resolve();
+                operation.operationId = 'asyncPostBar';
+              },
+            },
+          },
+          spec,
+        });
+
+        expect(spec.paths!['/foo']?.get?.operationId).toBe('asyncGetFoo');
+        expect(spec.paths!['/bar']?.post?.operationId).toBe('asyncPostBar');
+      });
+
+      it('Record-based operations still work as before', async () => {
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: {
+              'GET /foo': (operation) => {
+                operation.operationId = 'getFoo';
+              },
+              'POST /bar': (operation) => {
+                operation.operationId = 'postBar';
+              },
+            },
+          },
+          spec,
+        });
+
+        expect(spec.paths!['/foo']?.get?.operationId).toBe('getFoo');
+        expect(spec.paths!['/bar']?.post?.operationId).toBe('postBar');
+      });
+
+      it('handles spec without paths', async () => {
+        const fn = vi.fn();
+
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: fn,
+          },
+          spec,
+        });
+
+        expect(fn).not.toHaveBeenCalled();
+      });
+
+      it('handles all HTTP methods', async () => {
+        const fn = vi.fn();
+
+        const spec: OpenApi.V3_1_X = {
+          ...specMetadataV3,
+          paths: {
+            '/test': {
+              delete: { responses: {} } as any,
+              get: { responses: {} } as any,
+              head: { responses: {} } as any,
+              options: { responses: {} } as any,
+              patch: { responses: {} } as any,
+              post: { responses: {} } as any,
+              put: { responses: {} } as any,
+              trace: { responses: {} } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: fn,
+          },
+          spec,
+        });
+
+        expect(fn).toHaveBeenCalledTimes(8);
+        expect(fn).toHaveBeenCalledWith('get', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('put', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('post', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('delete', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('options', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('head', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('patch', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('trace', '/test', expect.any(Object));
+      });
+    });
+
+    describe('OpenAPI v2', () => {
+      it('bulk callback mutates all operations', async () => {
+        const spec: OpenApi.V2_0_X = {
+          ...specMetadataV2,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+              put: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: (method, path, operation) => {
+              operation.operationId = `${method}_${path.replace(/\//g, '_')}`;
+            },
+          },
+          spec,
+        });
+
+        expect(spec.paths!['/foo']?.get?.operationId).toBe('get__foo');
+        expect(spec.paths!['/foo']?.put?.operationId).toBe('put__foo');
+        expect(spec.paths!['/bar']?.post?.operationId).toBe('post__bar');
+      });
+
+      it('bulk callback receives correct parameters', async () => {
+        const fn = vi.fn();
+
+        const spec: OpenApi.V2_0_X = {
+          ...specMetadataV2,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: fn,
+          },
+          spec,
+        });
+
+        expect(fn).toHaveBeenCalledTimes(2);
+        expect(fn).toHaveBeenCalledWith('get', '/foo', spec.paths!['/foo']?.get);
+        expect(fn).toHaveBeenCalledWith('post', '/bar', spec.paths!['/bar']?.post);
+      });
+
+      it('supports async bulk callback', async () => {
+        const spec: OpenApi.V2_0_X = {
+          ...specMetadataV2,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: async (method, path, operation) => {
+              await Promise.resolve();
+              operation.operationId = `async_${method}_${path}`;
+            },
+          },
+          spec,
+        });
+
+        expect(spec.paths!['/foo']?.get?.operationId).toBe('async_get_/foo');
+        expect(spec.paths!['/bar']?.post?.operationId).toBe('async_post_/bar');
+      });
+
+      it('Record-based operations still work as before', async () => {
+        const spec: OpenApi.V2_0_X = {
+          ...specMetadataV2,
+          paths: {
+            '/bar': {
+              post: {
+                responses: {},
+              } as any,
+            },
+            '/foo': {
+              get: {
+                responses: {},
+              } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: {
+              'GET /foo': (operation) => {
+                operation.operationId = 'getFoo';
+              },
+              'POST /bar': (operation) => {
+                operation.operationId = 'postBar';
+              },
+            },
+          },
+          spec,
+        });
+
+        expect(spec.paths!['/foo']?.get?.operationId).toBe('getFoo');
+        expect(spec.paths!['/bar']?.post?.operationId).toBe('postBar');
+      });
+
+      it('handles all HTTP methods', async () => {
+        const fn = vi.fn();
+
+        const spec: OpenApi.V2_0_X = {
+          ...specMetadataV2,
+          paths: {
+            '/test': {
+              delete: { responses: {} } as any,
+              get: { responses: {} } as any,
+              head: { responses: {} } as any,
+              options: { responses: {} } as any,
+              patch: { responses: {} } as any,
+              post: { responses: {} } as any,
+              put: { responses: {} } as any,
+            },
+          },
+        };
+
+        await patchOpenApiSpec({
+          patchOptions: {
+            operations: fn,
+          },
+          spec,
+        });
+
+        expect(fn).toHaveBeenCalledTimes(7);
+        expect(fn).toHaveBeenCalledWith('get', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('put', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('post', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('delete', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('options', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('head', '/test', expect.any(Object));
+        expect(fn).toHaveBeenCalledWith('patch', '/test', expect.any(Object));
+      });
+    });
+  });
 });

packages/shared/src/openApi/shared/utils/patch.ts

···
     }
 
     if (patchOptions.operations && spec.paths) {
-      for (const key in patchOptions.operations) {
-        const [method, path] = key.split(' ');
-        if (!method || !path) continue;
+      if (typeof patchOptions.operations === 'function') {
+        // Bulk callback: iterate all operations
+        for (const [path, pathItem] of Object.entries(spec.paths)) {
+          if (!pathItem || typeof pathItem !== 'object') continue;
+          for (const method of [
+            'get',
+            'put',
+            'post',
+            'delete',
+            'options',
+            'head',
+            'patch',
+            'trace',
+          ]) {
+            const operation = pathItem[method as keyof typeof pathItem];
+            if (!operation || typeof operation !== 'object') continue;
+            await patchOptions.operations(method, path, operation as any);
+          }
+        }
+      } else {
+        // Record-based: iterate named operations
+        for (const key in patchOptions.operations) {
+          const [method, path] = key.split(' ');
+          if (!method || !path) continue;
 
-        const pathItem = spec.paths[path as keyof typeof spec.paths];
-        if (!pathItem) continue;
+          const pathItem = spec.paths[path as keyof typeof spec.paths];
+          if (!pathItem) continue;
 
-        const operation =
-          pathItem[method.toLocaleLowerCase() as keyof typeof pathItem] ||
-          pathItem[method.toLocaleUpperCase() as keyof typeof pathItem];
-        if (!operation || typeof operation !== 'object') continue;
+          const operation =
+            pathItem[method.toLocaleLowerCase() as keyof typeof pathItem] ||
+            pathItem[method.toLocaleUpperCase() as keyof typeof pathItem];
+          if (!operation || typeof operation !== 'object') continue;
 
-        const patchFn = patchOptions.operations[key]!;
-        patchFn(operation as any);
+          const patchFn = patchOptions.operations[key]!;
+          await patchFn(operation as any);
+        }
       }
     }
     return;
···
   }
 
   if (patchOptions.operations && spec.paths) {
-    for (const key in patchOptions.operations) {
-      const [method, path] = key.split(' ');
-      if (!method || !path) continue;
+    if (typeof patchOptions.operations === 'function') {
+      // Bulk callback: iterate all operations
+      for (const [path, pathItem] of Object.entries(spec.paths)) {
+        if (!pathItem || typeof pathItem !== 'object') continue;
+        for (const method of [
+          'get',
+          'put',
+          'post',
+          'delete',
+          'options',
+          'head',
+          'patch',
+          'trace',
+        ]) {
+          const operation = pathItem[method as keyof typeof pathItem];
+          if (!operation || typeof operation !== 'object') continue;
+          await patchOptions.operations(method, path, operation as any);
+        }
+      }
+    } else {
+      // Record-based: iterate named operations
+      for (const key in patchOptions.operations) {
+        const [method, path] = key.split(' ');
+        if (!method || !path) continue;
 
-      const pathItem = spec.paths[path as keyof typeof spec.paths];
-      if (!pathItem) continue;
+        const pathItem = spec.paths[path as keyof typeof spec.paths];
+        if (!pathItem) continue;
 
-      const operation =
-        pathItem[method.toLocaleLowerCase() as keyof typeof pathItem] ||
-        pathItem[method.toLocaleUpperCase() as keyof typeof pathItem];
-      if (!operation || typeof operation !== 'object') continue;
+        const operation =
+          pathItem[method.toLocaleLowerCase() as keyof typeof pathItem] ||
+          pathItem[method.toLocaleUpperCase() as keyof typeof pathItem];
+        if (!operation || typeof operation !== 'object') continue;
 
-      const patchFn = patchOptions.operations[key]!;
-      patchFn(operation as any);
+        const patchFn = patchOptions.operations[key]!;
+        await patchFn(operation as any);
+      }
     }
   }
 }