elysia-openapi-codegen 0.1.0

package/README.md

@@ -0,0 +1,357 @@
+# Elysia OpenAPI Code Generator
+
+Generate fully-typed React Query hooks and TypeScript interfaces from OpenAPI specifications. Perfect for Elysia.js APIs and any OpenAPI 3.x compliant backend.
+
+## Features
+
+- **Type-Safe Hooks**: Automatically generates React Query hooks with full TypeScript support
+- **OpenAPI 3.x Compatible**: Works with any valid OpenAPI specification
+- **Multiple Input Sources**: Fetch specs from URLs or local files
+- **Zero Configuration**: Simple CLI with sensible defaults
+- **React Query Integration**: Generates `useQuery` and `useMutation` hooks ready to use
+- **Flexible Arguments**: Supports both flag-based and positional arguments
+
+## Installation
+
+### Using Bun (Recommended)
+
+```bash
+bun add -d elysia-openapi-codegen
+```
+
+### Using npm
+
+```bash
+npm install --save-dev elysia-openapi-codegen
+```
+
+### Using yarn
+
+```bash
+yarn add -D elysia-openapi-codegen
+```
+
+### Global Installation
+
+```bash
+# Bun
+bun add -g elysia-openapi-codegen
+
+# npm
+npm install -g elysia-openapi-codegen
+```
+
+## Usage
+
+### CLI Flags
+
+```bash
+elysia-codegen -i <source> -o <output>
+```
+
+**Arguments:**
+- `-i, --input <source>` - OpenAPI spec source (URL or file path)
+- `-o, --output <output>` - Output directory for generated files
+- `-h, --help` - Show help message
+
+### Examples
+
+#### Using Flag Arguments
+
+```bash
+# From a URL
+elysia-codegen -i https://api.example.com/openapi.json -o ./src/api
+
+# From a local file
+elysia-codegen -i ./openapi.json -o ./generated
+
+# Using long-form flags
+elysia-codegen --input https://api.example.com/openapi.json --output ./src/api
+```
+
+#### Using Positional Arguments
+
+```bash
+# From a URL
+elysia-codegen https://api.example.com/openapi.json ./src/api
+
+# From a local file
+elysia-codegen ./openapi.json ./generated
+```
+
+#### With Bun
+
+```bash
+# Run directly with bun
+bun index.ts -i https://api.example.com/openapi.json -o ./src/api
+
+# Or using positional arguments
+bun index.ts https://api.example.com/openapi.json ./src/api
+```
+
+## Generated Code Usage
+
+The generator creates a single `generated.ts` file containing all types and hooks.
+
+### TypeScript Types
+
+All request/response types are automatically generated:
+
+```typescript
+import type { User, CreateUserBody, GetUsersResponse } from './generated';
+
+// Use types in your components
+const user: User = {
+  id: 1,
+  name: 'John Doe',
+  email: 'john@example.com'
+};
+```
+
+### React Query Hooks
+
+#### Query Hooks (GET requests)
+
+```typescript
+import { useGetUsers, useGetUserById } from './api/generated';
+
+function UsersList() {
+  // Simple query with no parameters
+  const { data, isLoading, error } = useGetUsers();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {data?.users.map(user => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+function UserProfile({ userId }: { userId: number }) {
+  // Query with parameters
+  const { data: user } = useGetUserById(
+    { id: userId },
+    {
+      enabled: !!userId, // React Query options
+      staleTime: 5000,
+    }
+  );
+
+  return <div>{user?.name}</div>;
+}
+```
+
+#### Mutation Hooks (POST, PUT, PATCH, DELETE)
+
+```typescript
+import { useCreateUser, useUpdateUser, useDeleteUser } from './api/generated';
+import { useQueryClient } from '@tanstack/react-query';
+
+function CreateUserForm() {
+  const queryClient = useQueryClient();
+
+  const { mutate, isPending } = useCreateUser({
+    onSuccess: () => {
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ['getUsers'] });
+    },
+  });
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+
+    mutate({
+      name: formData.get('name') as string,
+      email: formData.get('email') as string,
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  );
+}
+
+function UserActions({ userId }: { userId: number }) {
+  const queryClient = useQueryClient();
+
+  const { mutate: updateUser } = useUpdateUser({
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['getUserById', { id: userId }] });
+    },
+  });
+
+  const { mutate: deleteUser } = useDeleteUser({
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['getUsers'] });
+    },
+  });
+
+  return (
+    <div>
+      <button onClick={() => updateUser({ id: userId, name: 'Updated Name' })}>
+        Update
+      </button>
+      <button onClick={() => deleteUser({ id: userId })}>
+        Delete
+      </button>
+    </div>
+  );
+}
+```
+
+### Advanced Usage
+
+#### Custom Query Keys
+
+```typescript
+import { useGetUsers } from './api/generated';
+
+function FilteredUsers({ status }: { status: string }) {
+  const { data } = useGetUsers(
+    { status },
+    {
+      queryKey: ['users', status], // Custom query key
+      staleTime: 60000,
+      refetchOnWindowFocus: false,
+    }
+  );
+
+  return <div>{/* Render users */}</div>;
+}
+```
+
+#### Error Handling
+
+```typescript
+import { useCreateUser } from './api/generated';
+
+function CreateUserForm() {
+  const { mutate, error, isError } = useCreateUser({
+    onError: (error) => {
+      console.error('Failed to create user:', error);
+      // Show toast notification, etc.
+    },
+  });
+
+  return (
+    <div>
+      {isError && <div className="error">{error.message}</div>}
+      {/* Form fields */}
+    </div>
+  );
+}
+```
+
+#### Optimistic Updates
+
+```typescript
+import { useUpdateUser } from './api/generated';
+import { useQueryClient } from '@tanstack/react-query';
+
+function UserEditor({ userId }: { userId: number }) {
+  const queryClient = useQueryClient();
+
+  const { mutate } = useUpdateUser({
+    onMutate: async (newUser) => {
+      // Cancel outgoing refetches
+      await queryClient.cancelQueries({ queryKey: ['getUserById', { id: userId }] });
+
+      // Snapshot the previous value
+      const previousUser = queryClient.getQueryData(['getUserById', { id: userId }]);
+
+      // Optimistically update
+      queryClient.setQueryData(['getUserById', { id: userId }], newUser);
+
+      return { previousUser };
+    },
+    onError: (err, newUser, context) => {
+      // Rollback on error
+      queryClient.setQueryData(
+        ['getUserById', { id: userId }],
+        context?.previousUser
+      );
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['getUserById', { id: userId }] });
+    },
+  });
+
+  return <div>{/* Editor UI */}</div>;
+}
+```
+
+## Requirements
+
+- **TypeScript**: ^5.0.0
+- **@tanstack/react-query**: ^5.0.0 (peer dependency for generated code)
+- **React**: ^18.0.0 (peer dependency for generated code)
+
+## Project Structure
+
+```
+your-project/
+├── src/
+│   ├── api/
+│   │   └── generated.ts    # Generated by this tool
+│   ├── components/
+│   │   └── Users.tsx       # Your components using the hooks
+│   └── App.tsx
+├── openapi.json            # Your OpenAPI spec
+└── package.json
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+bun install
+
+# Run the generator locally
+bun index.ts -i ./example/openapi.json -o ./output
+```
+
+### Building
+
+This project uses Bun as the runtime. No build step is necessary for development.
+
+## How It Works
+
+1. **Fetches OpenAPI Spec**: Reads from a URL or local file
+2. **Generates TypeScript Types**: Creates interfaces from schema definitions
+3. **Creates React Query Hooks**: Generates typed hooks for each endpoint
+   - GET requests → `useQuery` hooks
+   - POST/PUT/PATCH/DELETE → `useMutation` hooks
+4. **Outputs Single File**: All types and hooks in one `generated.ts` file
+
+## Limitations
+
+- Only supports `application/json` content types
+- Uses the first server URL as the base URL
+- Assumes standard REST conventions for operations
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT
+
+## Related Projects
+
+- [Elysia](https://elysiajs.com/) - Fast and friendly Bun web framework
+- [TanStack Query](https://tanstack.com/query) - Powerful data synchronization for React
+- [OpenAPI](https://www.openapis.org/) - API specification standard

package/index.ts

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+
+/**
+ * Elysia OpenAPI Code Generator
+ * Generates typed React Query hooks from OpenAPI specifications.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import https from 'https';
+import http from 'http';
+
+interface OpenAPISpec {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        [key: string]: unknown;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, OpenAPIPathItem>;
+    components?: {
+        schemas?: Record<string, OpenAPISchema>;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+
+interface OpenAPIPathItem {
+    get?: OpenAPIOperation;
+    post?: OpenAPIOperation;
+    put?: OpenAPIOperation;
+    delete?: OpenAPIOperation;
+    patch?: OpenAPIOperation;
+    [key: string]: unknown;
+}
+
+interface OpenAPIOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters?: OpenAPIParameter[];
+    responses?: Record<string, OpenAPIResponse>;
+    requestBody?: {
+        content: {
+            [contentType: string]: {
+                schema: OpenAPISchema;
+            };
+        };
+    };
+    [key: string]: unknown;
+}
+
+interface OpenAPIParameter {
+    name: string;
+    in: 'query' | 'header' | 'path' | 'cookie';
+    description?: string;
+    required?: boolean;
+    schema?: OpenAPISchema;
+    [key: string]: unknown;
+}
+
+interface OpenAPIResponse {
+    description: string;
+    content?: {
+        [contentType: string]: {
+            schema: OpenAPISchema;
+        };
+    };
+    [key: string]: unknown;
+}
+
+interface OpenAPISchema {
+    type?: string;
+    items?: OpenAPISchema;
+    properties?: Record<string, OpenAPISchema>;
+    required?: string[];
+    $ref?: string;
+    nullable?: boolean;
+    anyOf?: OpenAPISchema[];
+    oneOf?: OpenAPISchema[];
+    allOf?: OpenAPISchema[];
+    [key: string]: unknown;
+}
+
+async function fetchSpec(source: string): Promise<OpenAPISpec> {
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        return new Promise((resolve, reject) => {
+            const client = source.startsWith('https://') ? https : http;
+            client.get(source, (res) => {
+                let data = '';
+                res.on('data', (chunk) => data += chunk);
+                res.on('end', () => {
+                    try {
+                        resolve(JSON.parse(data) as OpenAPISpec);
+                    } catch (e) {
+                        reject(new Error(`Failed to parse OpenAPI spec: ${(e as Error).message}`));
+                    }
+                });
+                res.on('error', reject);
+            });
+        });
+    }
+
+    return JSON.parse(fs.readFileSync(source, 'utf8')) as OpenAPISpec;
+}
+
+function resolveType(schema?: OpenAPISchema): string {
+    if (!schema) return 'any';
+
+    if (schema.$ref) {
+        return schema.$ref.split('/').pop() || 'any';
+    }
+
+    if (schema.type === 'array' && schema.items) {
+        return `Array<${resolveType(schema.items)}>`;
+    }
+
+    if (schema.type === 'object') {
+        if (!schema.properties) return 'Record<string, any>';
+
+        const props = Object.entries(schema.properties).map(([key, prop]) => {
+            const isRequired = schema.required?.includes(key);
+            const optional = isRequired ? '' : '?';
+            return `  ${key}${optional}: ${resolveType(prop)};`;
+        });
+
+        return `{\n${props.join('\n')}\n}`;
+    }
+
+    if (schema.anyOf || schema.oneOf) {
+        return (schema.anyOf || schema.oneOf || []).map(resolveType).join(' | ');
+    }
+
+    if (schema.allOf) {
+        return schema.allOf.map(resolveType).join(' & ');
+    }
+
+    if (schema.nullable) {
+        return `${resolveType({ ...schema, nullable: false })} | null`;
+    }
+
+    const typeMap: Record<string, string> = {
+        string: 'string',
+        number: 'number',
+        integer: 'number',
+        boolean: 'boolean',
+        null: 'null',
+    };
+
+    return (schema.type && typeMap[schema.type]) || 'any';
+}
+
+function generateTypes(spec: OpenAPISpec): string {
+    const definitions: string[] = [];
+
+    if (spec.components?.schemas) {
+        for (const [name, schema] of Object.entries(spec.components.schemas)) {
+            definitions.push(`export type ${name} = ${resolveType(schema)};`);
+        }
+    }
+
+    for (const [pathUrl, pathItem] of Object.entries(spec.paths)) {
+        for (const [method, operation] of Object.entries(pathItem)) {
+            if (!['get', 'post', 'put', 'patch', 'delete'].includes(method)) continue;
+
+            const op = operation as OpenAPIOperation;
+            const opId = op.operationId || `${method}${pathUrl.replace(/[^a-zA-Z0-9]/g, '')}`;
+            const response = op.responses?.['200'];
+
+            if (response?.content?.['application/json']?.schema) {
+                const responseType = resolveType(response.content['application/json'].schema);
+                definitions.push(`export type ${capitalize(opId)}Response = ${responseType};`);
+            }
+
+            const params = op.parameters || [];
+            if (params.length > 0) {
+                const paramProps = params.map(param => {
+                    const required = param.required ? '' : '?';
+                    return `  ${param.name}${required}: ${resolveType(param.schema)};`;
+                });
+                definitions.push(`export type ${capitalize(opId)}Params = {\n${paramProps.join('\n')}\n};`);
+            }
+
+            if (op.requestBody?.content?.['application/json']?.schema) {
+                const bodyType = resolveType(op.requestBody.content['application/json'].schema);
+                definitions.push(`export type ${capitalize(opId)}Body = ${bodyType};`);
+            }
+        }
+    }
+
+    return definitions.join('\n\n');
+}
+
+function generateHooks(spec: OpenAPISpec): string {
+    const hooks: string[] = [];
+    const baseUrl = spec.servers?.[0]?.url || '';
+
+    for (const [pathUrl, pathItem] of Object.entries(spec.paths)) {
+        for (const [method, operation] of Object.entries(pathItem)) {
+            if (!['get', 'post', 'put', 'patch', 'delete'].includes(method)) continue;
+
+            const op = operation as OpenAPIOperation;
+            const opId = op.operationId || `${method}${pathUrl.replace(/[^a-zA-Z0-9]/g, '')}`;
+
+            const hasResponse = !!op.responses?.['200']?.content?.['application/json']?.schema;
+            const responseType = hasResponse ? `${capitalize(opId)}Response` : 'any';
+
+            const params = op.parameters || [];
+            const hasParams = params.length > 0;
+            const paramsType = hasParams ? `${capitalize(opId)}Params` : 'void';
+
+            const hasBody = !!op.requestBody?.content?.['application/json']?.schema;
+            const bodyType = hasBody ? `${capitalize(opId)}Body` : 'void';
+
+            if (method === 'get') {
+                const queryParams = params.map(p => p.name);
+                const queryString = queryParams.length > 0
+                    ? `?${queryParams.map((p: string) => `\${params?.${p} !== undefined ? '${p}=' + params.${p} : ''}`).join('&')}`
+                    : '';
+
+                hooks.push(`
+export const use${capitalize(opId)} = (
+  params${hasParams ? '' : '?'}: ${paramsType},
+  options?: Omit<UseQueryOptions<${responseType}>, 'queryKey' | 'queryFn'>
+) => {
+  return useQuery<${responseType}>({
+    queryKey: ['${opId}', params],
+    queryFn: async () => {
+      const res = await fetch(\`\${baseUrl}${pathUrl}${queryString}\`);
+      if (!res.ok) throw new Error('API Error');
+      return res.json();
+    },
+    ...options,
+  });
+};`);
+            } else {
+                let inputType = 'void';
+                let inputArg = '';
+
+                if (hasBody) {
+                    inputType = bodyType;
+                    inputArg = 'body';
+                } else if (hasParams) {
+                    inputType = paramsType;
+                    inputArg = 'params';
+                }
+
+                const hasInput = inputType !== 'void';
+
+                hooks.push(`
+export const use${capitalize(opId)} = (
+  options?: UseMutationOptions<${responseType}, Error, ${inputType}>
+) => {
+  return useMutation<${responseType}, Error, ${inputType}>({
+    mutationFn: async (${hasInput ? inputArg : ''}) => {
+      const res = await fetch(\`\${baseUrl}${pathUrl}\`, {
+        method: '${method.toUpperCase()}',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(${hasInput ? inputArg : '{}'}),
+      });
+      if (!res.ok) throw new Error('API Error');
+      return res.json();
+    },
+    ...options,
+  });
+};`);
+            }
+        }
+    }
+
+    return hooks.join('\n');
+}
+
+function capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+async function parseArgs() {
+    const args = process.argv.slice(2);
+    const config = {
+        input: '',
+        output: '',
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg) continue;
+
+        if (arg === '-i' || arg === '--input') {
+            const value = args[++i];
+            if (!value) {
+                console.error(`Error: ${arg} flag requires a value`);
+                process.exit(1);
+            }
+            config.input = value;
+        } else if (arg === '-o' || arg === '--output') {
+            const value = args[++i];
+            if (!value) {
+                console.error(`Error: ${arg} flag requires a value`);
+                process.exit(1);
+            }
+            config.output = value;
+        } else if (!arg.startsWith('-')) {
+            if (!config.input) config.input = arg;
+            else if (!config.output) config.output = arg;
+        }
+    }
+
+    return config;
+}
+
+function showHelp() {
+    console.log(`
+Elysia OpenAPI Code Generator
+Generate React Query hooks and TypeScript types from OpenAPI specifications.
+
+Usage:
+  elysia-codegen -i <source> -o <output>
+  elysia-codegen --input <source> --output <output>
+  elysia-codegen <source> <output>
+
+Arguments:
+  -i, --input <source>    OpenAPI spec source (URL or file path)
+  -o, --output <output>   Output directory for generated files
+
+Examples:
+  # Using flags
+  elysia-codegen -i https://api.example.com/openapi.json -o ./src/api
+  elysia-codegen --input ./openapi.json --output ./generated
+
+  # Using positional arguments
+  elysia-codegen https://api.example.com/openapi.json ./src/api
+  elysia-codegen ./openapi.json ./generated
+`);
+}
+
+async function main() {
+    const args = process.argv.slice(2);
+
+    if (args.includes('-h') || args.includes('--help') || args.length === 0) {
+        showHelp();
+        process.exit(0);
+    }
+
+    const { input, output } = await parseArgs();
+
+    if (!input || !output) {
+        console.error('Error: Both input source and output directory are required.\n');
+        showHelp();
+        process.exit(1);
+    }
+
+    console.log('Fetching OpenAPI spec...');
+
+    try {
+        const spec = await fetchSpec(input);
+        const types = generateTypes(spec);
+        const hooks = generateHooks(spec);
+        const baseUrl = spec.servers?.[0]?.url || '';
+
+        const fileContent = `/* eslint-disable */
+/**
+ * Auto-generated by Elysia OpenAPI Codegen
+ */
+
+import { useQuery, useMutation, UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+
+const baseUrl = '${baseUrl}';
+
+${types}
+
+${hooks}
+`;
+
+        if (!fs.existsSync(output)) {
+            fs.mkdirSync(output, { recursive: true });
+        }
+
+        const outputPath = path.join(output, 'generated.ts');
+        fs.writeFileSync(outputPath, fileContent);
+
+        console.log(`Successfully generated hooks at ${outputPath}`);
+    } catch (err) {
+        console.error('Generation failed:', err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "elysia-openapi-codegen",
+  "version": "0.1.0",
+  "description": "Generate React Query hooks and fully typed TypeScript interfaces from Elysia OpenAPI specs.",
+  "module": "index.ts",
+  "type": "module",
+  "bin": {
+    "elysia-codegen": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "README.md"
+  ],
+  "author": "Khantamir mkhantamir77@gmail.com",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mkhantamir/elysia-openapi-codegen.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mkhantamir/elysia-openapi-codegen/issues"
+  },
+  "homepage": "https://github.com/mkhantamir/elysia-openapi-codegen#readme",
+  "keywords": [
+    "elysia",
+    "openapi",
+    "codegen",
+    "typescript",
+    "react-query",
+    "tanstack-query"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}