openapi-remote-codegen 0.1.0

package/src/__tests__/remote-functions.test.ts

@@ -0,0 +1,315 @@
+import { describe, it, expect } from 'vitest';
+import { generateRemoteFunctions } from '../generators/remote-functions.js';
+import { resolveConfig } from '../config.js';
+import type { OperationInfo, ParsedSpec } from '../types.js';
+
+const defaultConfig = resolveConfig({});
+
+function createOperation(overrides: Partial<OperationInfo> = {}): OperationInfo {
+  return {
+    operationId: 'Foods_GetFavorites',
+    tag: 'V4 Foods',
+    method: 'get',
+    path: '/api/v4/foods/favorites',
+    remoteType: 'query',
+    invalidates: [],
+    parameters: [],
+    isVoidResponse: false,
+    clientPropertyName: 'foodsV4',
+    ...overrides,
+  };
+}
+
+function getGeneratedFile(parsed: ParsedSpec, fileName: string): string {
+  const files = generateRemoteFunctions(parsed, defaultConfig);
+  const content = files.get(fileName);
+  if (!content) {
+    const available = Array.from(files.keys()).join(', ');
+    throw new Error(`File "${fileName}" not found. Available: ${available}`);
+  }
+  return content;
+}
+
+describe('generateRemoteFunctions', () => {
+  describe('imports', () => {
+    it('imports redirect from @sveltejs/kit', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation()],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("import { error, redirect } from '@sveltejs/kit';");
+    });
+  });
+
+  describe('auth error handling in query functions', () => {
+    it('includes 401 redirect in no-arg query catch block', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation()],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("const status = (err as any)?.status;");
+      expect(content).toContain("if (status === 401) { const { url } = getRequestEvent(); throw redirect(302, `/auth/login?returnUrl=${encodeURIComponent(url.pathname + url.search)}`); }");
+      expect(content).toContain("if (status === 403) throw error(403, 'Forbidden');");
+    });
+
+    it('includes 401 redirect in parameterized query catch block', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_GetById',
+          parameters: [{ name: 'id', in: 'path', required: true, type: 'string' }],
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("const status = (err as any)?.status;");
+      expect(content).toContain("if (status === 401) { const { url } = getRequestEvent(); throw redirect(302, `/auth/login?returnUrl=${encodeURIComponent(url.pathname + url.search)}`); }");
+      expect(content).toContain("if (status === 403) throw error(403, 'Forbidden');");
+    });
+
+    it('preserves existing error(500) fallback in query', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation()],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("throw error(500, 'Failed to get favorites');");
+    });
+  });
+
+  describe('auth error handling in command functions', () => {
+    it('includes 401 redirect in no-arg command catch block', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_SyncAll',
+          remoteType: 'command',
+          isVoidResponse: true,
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("const status = (err as any)?.status;");
+      expect(content).toContain("if (status === 401) { const { url } = getRequestEvent(); throw redirect(302, `/auth/login?returnUrl=${encodeURIComponent(url.pathname + url.search)}`); }");
+      expect(content).toContain("if (status === 403) throw error(403, 'Forbidden');");
+    });
+
+    it('includes 401 redirect in parameterized command catch block', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_DeleteFood',
+          remoteType: 'command',
+          isVoidResponse: true,
+          parameters: [{ name: 'id', in: 'path', required: true, type: 'string' }],
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("const status = (err as any)?.status;");
+      expect(content).toContain("if (status === 401) { const { url } = getRequestEvent(); throw redirect(302, `/auth/login?returnUrl=${encodeURIComponent(url.pathname + url.search)}`); }");
+      expect(content).toContain("if (status === 403) throw error(403, 'Forbidden');");
+    });
+
+    it('preserves existing error(500) fallback in command', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_DeleteFood',
+          remoteType: 'command',
+          isVoidResponse: true,
+          parameters: [{ name: 'id', in: 'path', required: true, type: 'string' }],
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("throw error(500, 'Failed to delete food');");
+    });
+  });
+
+  describe('catch block ordering', () => {
+    it('places auth checks before console.error in query', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation()],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      const statusIndex = content.indexOf("const status = (err as any)?.status;");
+      const redirectIndex = content.indexOf("if (status === 401) {");
+      const forbiddenIndex = content.indexOf("if (status === 403) throw error(403, 'Forbidden');");
+      const consoleIndex = content.indexOf("console.error('Error in foodsV4.getFavorites:', err);");
+      const error500Index = content.indexOf("throw error(500, 'Failed to get favorites');");
+
+      expect(statusIndex).toBeLessThan(redirectIndex);
+      expect(redirectIndex).toBeLessThan(forbiddenIndex);
+      expect(forbiddenIndex).toBeLessThan(consoleIndex);
+      expect(consoleIndex).toBeLessThan(error500Index);
+    });
+
+    it('places auth checks before console.error in command', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_SyncAll',
+          remoteType: 'command',
+          isVoidResponse: true,
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      const statusIndex = content.indexOf("const status = (err as any)?.status;");
+      const redirectIndex = content.indexOf("if (status === 401) {");
+      const forbiddenIndex = content.indexOf("if (status === 403) throw error(403, 'Forbidden');");
+      const consoleIndex = content.indexOf("console.error('Error in foodsV4.syncAll:', err);");
+      const error500Index = content.indexOf("throw error(500, 'Failed to sync all');");
+
+      expect(statusIndex).toBeLessThan(redirectIndex);
+      expect(redirectIndex).toBeLessThan(forbiddenIndex);
+      expect(forbiddenIndex).toBeLessThan(consoleIndex);
+      expect(consoleIndex).toBeLessThan(error500Index);
+    });
+  });
+
+  describe('form functions', () => {
+    it('generates form() wrapper for form operations', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_AddFavorite',
+          remoteType: 'form',
+          requestBodySchema: 'AddFavoriteRequestSchema',
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain('= form(');
+      expect(content).not.toContain('= command(');
+    });
+
+    it('imports form from $app/server when forms present', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_AddFavorite',
+          remoteType: 'form',
+          requestBodySchema: 'AddFavoriteRequestSchema',
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("import { getRequestEvent, form } from '$app/server'");
+    });
+
+    it('imports invalid from @sveltejs/kit when forms present', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_AddFavorite',
+          remoteType: 'form',
+          requestBodySchema: 'AddFavoriteRequestSchema',
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain("import { error, redirect, invalid } from '@sveltejs/kit'");
+    });
+
+    it('includes refresh calls in form functions', () => {
+      const parsed: ParsedSpec = {
+        operations: [
+          createOperation({
+            operationId: 'Foods_GetFavorites',
+            remoteType: 'query',
+          }),
+          createOperation({
+            operationId: 'Foods_AddFavorite',
+            remoteType: 'form',
+            requestBodySchema: 'AddFavoriteRequestSchema',
+            invalidates: ['GetFavorites'],
+          }),
+        ],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain('refresh()');
+    });
+
+    it('does not import invalid when no forms present', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation()],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).not.toContain('invalid');
+    });
+  });
+
+  describe('batch query functions', () => {
+    it('generates query.batch() for batch queries', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_GetById',
+          remoteType: 'query',
+          isBatch: true,
+          parameters: [{ name: 'id', in: 'path', required: true, type: 'string' }],
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain('= query.batch(');
+    });
+
+    it('falls back to regular query for no-arg batch', () => {
+      const parsed: ParsedSpec = {
+        operations: [createOperation({
+          operationId: 'Foods_GetAll',
+          remoteType: 'query',
+          isBatch: true,
+          parameters: [],
+        })],
+        tags: ['V4 Foods'],
+      };
+
+      const content = getGeneratedFile(parsed, 'foods.generated.remote.ts');
+      expect(content).toContain('= query(async');
+    });
+  });
+
+  describe('config customization', () => {
+    it('uses custom import paths from config', () => {
+      const config = resolveConfig({
+        imports: { server: '@my/server', kit: '@my/kit', schemas: '@my/schemas', apiTypes: '@my/types', zod: 'zod4' },
+      });
+      const parsed: ParsedSpec = {
+        operations: [createOperation()],
+        tags: ['V4 Foods'],
+      };
+      const files = generateRemoteFunctions(parsed, config);
+      const content = files.get('foods.generated.remote.ts')!;
+      expect(content).toContain("from '@my/server'");
+      expect(content).toContain("from '@my/kit'");
+    });
+
+    it('uses custom client access expression', () => {
+      const config = resolveConfig({
+        clientAccess: 'container.resolve("ApiClient")',
+      });
+      const parsed: ParsedSpec = {
+        operations: [createOperation()],
+        tags: ['V4 Foods'],
+      };
+      const files = generateRemoteFunctions(parsed, config);
+      const content = files.get('foods.generated.remote.ts')!;
+      expect(content).toContain('container.resolve("ApiClient")');
+    });
+  });
+});

package/src/config.ts

@@ -0,0 +1,95 @@
+export interface ImportPaths {
+  /** Module providing query, command, form, getRequestEvent. Default: '$app/server' */
+  server: string;
+  /** Module providing error, redirect. Default: '@sveltejs/kit' */
+  kit: string;
+  /** Module providing Zod schemas. Default: '$lib/api/generated/schemas' */
+  schemas: string;
+  /** Module providing API types/enums. Default: '$api' */
+  apiTypes: string;
+  /** Zod module. Default: 'zod' */
+  zod: string;
+}
+
+export interface ErrorHandling {
+  /** Code to execute on 401. Has access to `url` (current URL). Default: redirect to /auth/login */
+  on401: string;
+  /** Code to execute on 403. Default: error(403, 'Forbidden') */
+  on403: string;
+  /** Function that takes a human-readable function name and returns code for 500. */
+  on500: (functionName: string) => string;
+}
+
+export interface GeneratorConfig {
+  /** Path to the OpenAPI spec JSON file. Default: './openapi.json' */
+  openApiPath: string;
+  /** Base output directory. Default: './src/lib' */
+  outputDir: string;
+  /** Subdirectory within outputDir for remote function files. Default: 'api/generated' */
+  remoteFunctionsOutput: string;
+  /** Path within outputDir for the ApiClient wrapper. Default: 'api/api-client.generated.ts' */
+  apiClientOutput: string;
+  /** Import paths used in generated code. */
+  imports: ImportPaths;
+  /** Expression to access the API client in generated functions. Default: 'getRequestEvent().locals.apiClient' */
+  clientAccess: string;
+  /** Error handling templates for generated catch blocks. */
+  errorHandling: ErrorHandling;
+  /** Path to the NSwag-generated client module (used in ApiClient imports). Default: './generated/api-client' */
+  nswagClientPath: string;
+}
+
+export type UserConfig = Partial<Omit<GeneratorConfig, 'imports' | 'errorHandling'>> & {
+  imports?: Partial<ImportPaths>;
+  errorHandling?: Partial<ErrorHandling>;
+};
+
+const DEFAULT_IMPORTS: ImportPaths = {
+  server: '$app/server',
+  kit: '@sveltejs/kit',
+  schemas: '$lib/api/generated/schemas',
+  apiTypes: '$api',
+  zod: 'zod',
+};
+
+const DEFAULT_ERROR_HANDLING: ErrorHandling = {
+  on401: 'const { url } = getRequestEvent(); throw redirect(302, `/auth/login?returnUrl=${encodeURIComponent(url.pathname + url.search)}`)',
+  on403: "throw error(403, 'Forbidden')",
+  on500: (functionName: string) => `throw error(500, 'Failed to ${functionName}')`,
+};
+
+const DEFAULTS: GeneratorConfig = {
+  openApiPath: './openapi.json',
+  outputDir: './src/lib',
+  remoteFunctionsOutput: 'api/generated',
+  apiClientOutput: 'api/api-client.generated.ts',
+  imports: DEFAULT_IMPORTS,
+  clientAccess: 'getRequestEvent().locals.apiClient',
+  errorHandling: DEFAULT_ERROR_HANDLING,
+  nswagClientPath: './generated/api-client',
+};
+
+/** Type-helper for config files. Returns the input as-is. */
+export function defineConfig(config: UserConfig): UserConfig {
+  return config;
+}
+
+/** Merge user config with defaults to produce a fully resolved config. */
+export function resolveConfig(user: UserConfig): GeneratorConfig {
+  return {
+    openApiPath: user.openApiPath ?? DEFAULTS.openApiPath,
+    outputDir: user.outputDir ?? DEFAULTS.outputDir,
+    remoteFunctionsOutput: user.remoteFunctionsOutput ?? DEFAULTS.remoteFunctionsOutput,
+    apiClientOutput: user.apiClientOutput ?? DEFAULTS.apiClientOutput,
+    imports: {
+      ...DEFAULTS.imports,
+      ...user.imports,
+    },
+    clientAccess: user.clientAccess ?? DEFAULTS.clientAccess,
+    errorHandling: {
+      ...DEFAULTS.errorHandling,
+      ...user.errorHandling,
+    },
+    nswagClientPath: user.nswagClientPath ?? DEFAULTS.nswagClientPath,
+  };
+}

package/src/generators/api-client.ts

@@ -0,0 +1,82 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { GeneratorConfig } from '../config.js';
+import { getClientPropertyName } from '../utils/client-mapping.js';
+
+/**
+ * Generate the ApiClient wrapper class.
+ */
+export function generateApiClient(spec: OpenAPIV3.Document, config: GeneratorConfig): string {
+  // Map each tag to its NSwag client class name and optional client property override
+  type TagInfo = { prefix: string; clientProperty?: string };
+  const tagInfo = new Map<string, TagInfo>();
+
+  for (const pathItem of Object.values(spec.paths ?? {})) {
+    if (!pathItem) continue;
+
+    for (const method of ['get', 'post', 'put', 'patch', 'delete'] as const) {
+      const operation = pathItem[method] as (OpenAPIV3.OperationObject & { 'x-client-property'?: string }) | undefined;
+      if (operation?.tags?.[0] && operation.operationId) {
+        const tag = operation.tags[0];
+        if (!tagInfo.has(tag)) {
+          const prefix = operation.operationId.split('_')[0];
+          tagInfo.set(tag, {
+            prefix,
+            clientProperty: operation['x-client-property'],
+          });
+        }
+      }
+    }
+  }
+
+  // Deduplicate by className (NSwag merges tags like "Treatments" and "V4 Treatments"
+  // into a single TreatmentsClient)
+  const seen = new Set<string>();
+  const clients = Array.from(tagInfo.entries())
+    .map(([tag, info]) => ({
+      className: `${info.prefix}Client`,
+      propertyName: info.clientProperty ?? getClientPropertyName(tag),
+    }))
+    .filter(c => {
+      if (seen.has(c.className)) return false;
+      seen.add(c.className);
+      return true;
+    })
+    .sort((a, b) => a.propertyName.localeCompare(b.propertyName));
+
+  const imports = clients.map(c => c.className).join(',\n  ');
+  const properties = clients.map(c => `  public readonly ${c.propertyName}: ${c.className};`).join('\n');
+  const initializers = clients.map(c =>
+    `    this.${c.propertyName} = new ${c.className}(apiBaseUrl, http);`
+  ).join('\n');
+
+  return `// AUTO-GENERATED - DO NOT EDIT
+// Generated by openapi-remote-codegen
+// Source: openapi.json
+//
+import {
+  ${imports}
+} from "${config.nswagClientPath}";
+
+/**
+ * API client wrapper.
+ * Provides typed access to all backend endpoints.
+ */
+export class ApiClient {
+  public readonly baseUrl: string;
+${properties}
+
+  constructor(
+    baseUrl: string,
+    http?: { fetch(url: RequestInfo, init?: RequestInit): Promise<Response> }
+  ) {
+    const apiBaseUrl = baseUrl;
+    this.baseUrl = apiBaseUrl;
+
+${initializers}
+  }
+}
+
+// Export the generated client types for use in components
+export * from "${config.nswagClientPath}";
+`;
+}