openapi-remote-codegen 0.1.0

package/README.md

@@ -0,0 +1,173 @@
+# openapi-remote-codegen
+
+TypeScript CLI and library that generates type-safe SvelteKit remote functions from OpenAPI specs annotated with `x-remote-*` extensions.
+
+## Installation
+
+```bash
+npm install -D openapi-remote-codegen
+```
+
+## Zero-Config Usage
+
+If your OpenAPI spec lives at `./openapi.json`, just run:
+
+```bash
+npx openapi-remote-codegen
+```
+
+The generator reads the spec, finds operations annotated with `x-remote-type`, and writes generated files to `./src/lib/api/generated/`.
+
+## Configuration
+
+Create a `remote-codegen.config.ts` (or `.js` / `.mjs`) in your project root:
+
+```ts
+import { defineConfig } from 'openapi-remote-codegen/config';
+
+export default defineConfig({
+  openApiPath: './openapi.json',
+  outputDir: './src/lib',
+});
+```
+
+### Config Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `openApiPath` | `string` | `'./openapi.json'` | Path to the OpenAPI spec JSON file |
+| `outputDir` | `string` | `'./src/lib'` | Base output directory for generated files |
+| `remoteFunctionsOutput` | `string` | `'api/generated'` | Subdirectory within `outputDir` for remote function files |
+| `apiClientOutput` | `string` | `'api/api-client.generated.ts'` | Path within `outputDir` for the ApiClient wrapper |
+| `clientAccess` | `string` | `'getRequestEvent().locals.apiClient'` | Expression to access the API client in generated functions |
+| `nswagClientPath` | `string` | `'./generated/api-client'` | Path to the NSwag-generated client module |
+| `imports` | `ImportPaths` | See below | Module paths used in generated `import` statements |
+| `errorHandling` | `ErrorHandling` | See below | Templates for generated `catch` blocks |
+
+### `imports`
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `server` | `'$app/server'` | Module providing `query`, `command`, `form`, `getRequestEvent` |
+| `kit` | `'@sveltejs/kit'` | Module providing `error`, `redirect` |
+| `schemas` | `'$lib/api/generated/schemas'` | Module providing Zod schemas |
+| `apiTypes` | `'$api'` | Module providing API types and enums |
+| `zod` | `'zod'` | Zod module |
+
+### `errorHandling`
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `on401` | Redirect to `/auth/login` | Code to execute on 401 (has access to `url`) |
+| `on403` | `error(403, 'Forbidden')` | Code to execute on 403 |
+| `on500` | `error(500, 'Failed to ...')` | Function taking a human-readable name, returns code for 500 |
+
+## CLI Flags
+
+```bash
+npx openapi-remote-codegen [options]
+
+Options:
+  --config <path>    Path to config file (skips auto-discovery)
+```
+
+### Config File Discovery
+
+When `--config` is not provided, the CLI looks for these files in the current directory (first match wins):
+
+1. `remote-codegen.config.ts`
+2. `remote-codegen.config.js`
+3. `remote-codegen.config.mjs`
+
+If none are found, all defaults apply.
+
+## Generated Output
+
+The generator produces one file per OpenAPI tag (e.g., `foods.generated.remote.ts`) plus an `index.ts` barrel export and an `api-client.generated.ts` wrapper. Stale generated files are automatically cleaned up.
+
+### Example: Query
+
+```ts
+// foods.generated.remote.ts
+import { query, getRequestEvent } from '$app/server';
+import { error, redirect } from '@sveltejs/kit';
+
+export const getFavorites = query(async () => {
+  try {
+    const apiClient = getRequestEvent().locals.apiClient;
+    return await apiClient.foodsV4.getFavorites();
+  } catch (err) {
+    const status = (err as any)?.status;
+    if (status === 401) { /* redirect to login */ }
+    if (status === 403) throw error(403, 'Forbidden');
+    throw error(500, 'Failed to get favorites');
+  }
+});
+```
+
+### Example: Command with Invalidation
+
+```ts
+export const createFood = command(async (data: CreateFoodDto) => {
+  try {
+    const apiClient = getRequestEvent().locals.apiClient;
+    return await apiClient.foodsV4.createFood(data);
+  } catch (err) {
+    // ... error handling
+  }
+}, { invalidates: [getFavorites] });
+```
+
+## Programmatic API
+
+The package also exports its core pipeline for integration into build tools or custom workflows:
+
+```ts
+import {
+  parseOpenApiSpec,
+  generateRemoteFunctions,
+  generateApiClient,
+  resolveConfig,
+  defineConfig,
+} from 'openapi-remote-codegen';
+```
+
+```ts
+import { readFileSync } from 'fs';
+import { resolveConfig, parseOpenApiSpec, generateRemoteFunctions } from 'openapi-remote-codegen';
+
+const config = resolveConfig({ openApiPath: './my-spec.json' });
+const spec = JSON.parse(readFileSync(config.openApiPath, 'utf-8'));
+const parsed = parseOpenApiSpec(spec);
+const files = generateRemoteFunctions(parsed, config);
+
+for (const [fileName, content] of files) {
+  console.log(fileName, content.length);
+}
+```
+
+### Exported Types
+
+```ts
+import type {
+  GeneratorConfig,
+  UserConfig,
+  ImportPaths,
+  ErrorHandling,
+  ParsedSpec,
+  OperationInfo,
+  ParameterInfo,
+  RemoteType,
+} from 'openapi-remote-codegen';
+```
+
+## How It Works
+
+1. **Parse** -- The OpenAPI JSON spec is read and scanned for operations containing `x-remote-type` extension data.
+2. **Classify** -- Each annotated operation is classified as a `query`, `command`, or `form` and its parameters, request body schema, and response type are extracted.
+3. **Generate** -- Operations are grouped by tag. For each tag, a `.generated.remote.ts` file is emitted with typed wrapper functions. An `ApiClient` wrapper and barrel `index.ts` are also generated.
+4. **Write** -- Files are written to the configured output directory. Previously generated files that no longer correspond to a tag are removed.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,46 @@
+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>;
+};
+/** Type-helper for config files. Returns the input as-is. */
+export declare function defineConfig(config: UserConfig): UserConfig;
+/** Merge user config with defaults to produce a fully resolved config. */
+export declare function resolveConfig(user: UserConfig): GeneratorConfig;

package/dist/config.js

@@ -0,0 +1,45 @@
+const DEFAULT_IMPORTS = {
+    server: '$app/server',
+    kit: '@sveltejs/kit',
+    schemas: '$lib/api/generated/schemas',
+    apiTypes: '$api',
+    zod: 'zod',
+};
+const DEFAULT_ERROR_HANDLING = {
+    on401: 'const { url } = getRequestEvent(); throw redirect(302, `/auth/login?returnUrl=${encodeURIComponent(url.pathname + url.search)}`)',
+    on403: "throw error(403, 'Forbidden')",
+    on500: (functionName) => `throw error(500, 'Failed to ${functionName}')`,
+};
+const DEFAULTS = {
+    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) {
+    return config;
+}
+/** Merge user config with defaults to produce a fully resolved config. */
+export function resolveConfig(user) {
+    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/dist/generators/api-client.d.ts

@@ -0,0 +1,6 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { GeneratorConfig } from '../config.js';
+/**
+ * Generate the ApiClient wrapper class.
+ */
+export declare function generateApiClient(spec: OpenAPIV3.Document, config: GeneratorConfig): string;

package/dist/generators/api-client.js

@@ -0,0 +1,72 @@
+import { getClientPropertyName } from '../utils/client-mapping.js';
+/**
+ * Generate the ApiClient wrapper class.
+ */
+export function generateApiClient(spec, config) {
+    const tagInfo = new Map();
+    for (const pathItem of Object.values(spec.paths ?? {})) {
+        if (!pathItem)
+            continue;
+        for (const method of ['get', 'post', 'put', 'patch', 'delete']) {
+            const operation = pathItem[method];
+            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();
+    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}";
+`;
+}

package/dist/generators/remote-functions.d.ts

@@ -0,0 +1,3 @@
+import type { GeneratorConfig } from '../config.js';
+import type { ParsedSpec } from '../types.js';
+export declare function generateRemoteFunctions(parsed: ParsedSpec, config: GeneratorConfig): Map<string, string>;