nuxt-openapi-hyperfetch 0.1.0-alpha.1

package/docs/QUICK-START.md

@@ -0,0 +1,323 @@
+# 🚀 Quick Start - Understand in 5 Minutes
+
+> **For AI Assistants & New Developers**: This is your entry point to understand the codebase quickly.
+
+## What is this?
+
+**Nuxt Generator** is a CLI tool that automatically converts OpenAPI/Swagger specifications into type-safe Nuxt 3 composables.
+
+```
+OpenAPI/Swagger → TypeScript Client → Nuxt Composables
+   (swagger.yaml)    (PetApi.ts)       (useFetchAddPet)
+```
+
+## Generator Backends
+
+The tool supports two backends for **Stage 1** (OpenAPI → TypeScript Client). You choose at runtime:
+
+| Backend | Command | Requires | Output format |
+|---|---|---|---|
+| **OpenAPI Generator** (official) | `@openapitools/openapi-generator-cli` | Java 11+ | `apis/PetApi.ts`, `models/` |
+| **Hey API** | `@hey-api/openapi-ts` | Node.js only | `sdk.gen.ts`, `types.gen.ts` |
+
+Both produce the same final Nuxt composables. The choice affects only Stage 1 output and the parser used in Stage 2.
+
+> **Note**: If you select the official backend and Java is not installed, the CLI will abort with an installation link.
+
+## Core Flow
+
+```mermaid
+graph LR
+    A[OpenAPI Spec] --> B{Backend choice}
+    B -->|official| C1[openapi-generator-cli]
+    B -->|heyapi| C2[@hey-api/openapi-ts]
+    C1 --> D[ts-morph Parser]
+    C2 --> D
+    D --> E[Template Generator]
+    E --> F[Nuxt Composables]
+```
+
+### Step by Step
+
+1. **Select backend** — official (Java) or heyapi (Node.js)
+2. **Stage 1** — chosen backend generates TypeScript client code from swagger.yaml
+3. **Parser** (ts-morph) reads generated TypeScript and extracts API info
+4. **Template Generator** creates Nuxt composables from extracted info
+5. **Runtime Files** are copied to user's project (wrappers, helpers)
+
+## 3 Critical Concepts
+
+### 1. Two-Stage Generation
+
+**Stage 1: OpenAPI → TypeScript Client** (two backend options)
+
+```bash
+# Option A: official (requires Java 11+)
+npx @openapitools/openapi-generator-cli generate \
+  -i swagger.yaml -g typescript-fetch -o ./output
+# Generates: apis/PetApi.ts, models/, runtime.ts
+
+# Option B: heyapi (Node.js only)
+npx @hey-api/openapi-ts -i swagger.yaml -o ./output
+# Generates: sdk.gen.ts, types.gen.ts, client.gen.ts
+```
+
+**Stage 2: TypeScript Fetch → Nuxt Composables**
+
+Our tool parses `PetApi.ts` and generates:
+
+```typescript
+// Generated by our tool
+export const useFetchAddPet = (params, options) => {
+  return useApiRequest<Pet>('/pet', {
+    method: 'POST',
+    body: params.pet,
+    ...options,
+  });
+};
+```
+
+### 2. Wrapper Pattern
+
+We DON'T generate direct `useFetch()` calls. We use a **wrapper**:
+
+```
+useFetchAddPet → useApiRequest → useFetch (Nuxt native)
+                     ↑
+                  Callbacks, auth, interceptors
+```
+
+**Why?** Adds lifecycle callbacks & global behaviors without modifying generated code.
+
+### 3. Runtime vs Build-time
+
+| File Type        | Generated? | Copied to user? | User modifiable? |
+| ---------------- | ---------- | --------------- | ---------------- |
+| Composables      | ✅ Always  | ✅              | ❌ (regenerated) |
+| Runtime wrappers | ❌         | ✅ (once)       | ✅ (safe)        |
+| Plugin templates | ❌         | ✅ (once)       | ✅ (safe)        |
+| CLI tool itself  | ❌         | ❌              | ✅ (you edit)    |
+
+## Key Files (Read These First)
+
+### 1. **CLI Entry** - `src/index.ts`
+
+Starts here. Uses Commander.js for CLI commands.
+
+```typescript
+program
+  .command('generate')
+  .option('-i, --input <file>', 'OpenAPI file')
+  .option('-o, --output <dir>', 'Output directory')
+  .action(async (options) => {
+    // Orchestrates generation
+  });
+```
+
+### 2. **Main Generator** - `src/generators/use-fetch/generator.ts`
+
+Orchestrates the generation process:
+
+1. Scans for API files
+2. Calls parser
+3. Calls template generator
+4. Writes files
+5. Formats with Prettier
+
+### 3. **Parser** - `src/generators/use-fetch/parser.ts`
+
+Uses ts-morph to extract API info from TypeScript:
+
+```typescript
+// Extracts this pattern:
+async addPetRequestOpts(requestParameters): Promise<RequestOpts> {
+  return {
+    path: '/pet',                     // → method.path
+    method: 'POST',                   // → method.method
+    body: requestParameters['pet']    // → method.bodyField
+  }
+}
+```
+
+### 4. **Templates** - `src/generators/use-fetch/templates.ts`
+
+Generates composable code:
+
+```typescript
+function generateFunctionBody(method: MethodInfo): string {
+  return `export const ${method.composableName} = (
+    params: MaybeRef<${method.requestType}>,
+    options?: ApiRequestOptions<${method.responseType}>
+  ) => {
+    const p = isRef(params) ? params : shallowRef(params)
+    return useApiRequest<${method.responseType}>(
+      () => \`${url}\`,   // URL as function → reactive
+      { ...fetchOptions, ...options }
+    )
+  }`;
+}
+```
+
+### 5. **Runtime Wrapper** - `src/generators/use-fetch/runtime/useApiRequest.ts`
+
+Copied to user's project. Adds callbacks to useFetch:
+
+```typescript
+export function useApiRequest<T>(
+  url: string | (() => string), // supports reactive URL
+  options?: ApiRequestOptions<T>
+) {
+  const { onRequest, onSuccess, onError, onFinish, ...fetchOptions } = options || {};
+
+  // Merge local callbacks with global callbacks (from plugin)
+  const mergedCallbacks = mergeCallbacks(url, { onRequest, onSuccess, onError, onFinish });
+
+  // Apply global headers
+  const modifiedOptions = { ...fetchOptions, ...getGlobalHeaders() };
+
+  // Execute onRequest interceptor
+  if (mergedCallbacks.onRequest) {
+    applyRequestModifications(modifiedOptions, mergedCallbacks.onRequest(requestContext));
+  }
+
+  const result = useFetch<T>(url, modifiedOptions);
+
+  // Watch for data, error, and pending state changes
+  watch(
+    () => [result.data.value, result.error.value, result.pending.value] as const,
+    async ([data, error, pending]) => {
+      if (data) await mergedCallbacks.onSuccess?.(data);
+      if (error) await mergedCallbacks.onError?.(error);
+      if (!pending) await mergedCallbacks.onFinish?.();
+    }
+  );
+
+  return result;
+}
+```
+
+## Project Structure Overview
+
+```
+nuxt-generator/
+├── src/
+│   ├── index.ts                    # ⭐ START: CLI entry point
+│   ├── generate.ts                 # OpenAPI Generator wrapper
+│   └── generators/
+│       ├── shared/                 # Common code
+│       │   ├── types.ts            # MethodInfo interface
+│       │   ├── runtime/
+│       │   │   └── apiHelpers.ts   # Callbacks, auth, transforms
+│       │   └── templates/
+│       │       └── api-callbacks-plugin.ts  # Global callbacks template
+│       │
+│       ├── use-fetch/              # ⭐ Main generator
+│       │   ├── parser.ts           # Extract API info (ts-morph)
+│       │   ├── templates.ts        # Generate composables
+│       │   ├── generator.ts        # Orchestration
+│       │   └── runtime/
+│       │       └── useApiRequest.ts  # Wrapper (copied to user)
+│       │
+│       ├── use-async-data/         # Alternative generator
+│       │   └── ... (similar structure)
+│       │
+│       └── nuxt-server/            # Server routes generator
+│           ├── bff-templates.ts    # BFF pattern support
+│           └── ... (similar structure)
+│
+├── dist/                           # Compiled JavaScript
+└── docs/                           # 📚 You are here
+```
+
+## Most Common Tasks
+
+### Debugging a Parser Error
+
+1. Check error message for method name
+2. Open `src/generators/use-fetch/parser.ts`
+3. Look at `extractMethodInfo()` function (line ~81)
+4. Add `console.log()` to see what's being parsed
+5. Run: `npm run build && node dist/index.js generate -i swagger.yaml -o ./test`
+
+### Adding a New Generator Type
+
+1. Copy `src/generators/use-fetch/` → `src/generators/your-generator/`
+2. Modify `templates.ts` to generate your format
+3. Update `runtime/` wrapper if needed
+4. Add to CLI choices in `src/index.ts`
+5. Test: `npm run build && node dist/index.js generate`
+
+### Modifying Callback Behavior
+
+1. Edit `src/generators/shared/runtime/apiHelpers.ts`
+2. Modify `mergeCallbacks()` function
+3. Update runtime wrappers to use new logic
+4. Rebuild: `npm run build`
+5. Regenerate test output to verify
+
+### Changing Generated Code Format
+
+1. Edit `src/generators/use-fetch/templates.ts`
+2. Modify `generateFunctionBody()` or related functions
+3. Test template with: `npm run build && npm run generator`
+4. Check output in `swagger/composables/`
+
+## Technology Stack Quick Ref
+
+| Library                 | Purpose                   | Used in        |
+| ----------------------- | ------------------------- | -------------- |
+| `commander`             | CLI commands & args       | `src/index.ts` |
+| `@clack/prompts`        | Interactive prompts       | `src/cli/`     |
+| `ts-morph`              | TypeScript AST parsing    | `parser.ts`    |
+| `openapi-generator-cli` | Generate typescript-fetch | `generate.ts`  |
+| `prettier`              | Format generated code     | `generator.ts` |
+| `change-case`           | String conversions        | `templates.ts` |
+| `fs-extra`              | File operations           | Everywhere     |
+
+## Next Steps
+
+- **Architecture Details**: See [ARCHITECTURE.md](./ARCHITECTURE.md)
+- **API Reference**: See [API-REFERENCE.md](./API-REFERENCE.md)
+- **Development Guide**: See [DEVELOPMENT.md](./DEVELOPMENT.md)
+- **Troubleshooting**: See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+- **Contributing**: See [../CONTRIBUTING.md](../CONTRIBUTING.md)
+
+## Quick Commands
+
+```bash
+# Build
+npm run build
+
+# Generate from example swagger
+npm run generator
+
+# Generate specific type
+echo "useFetch" | npm run generator
+
+# Test generation
+node dist/index.js generate -i swagger.yaml -o ./test-output
+
+# Validate code quality
+npm run validate
+
+# Format + lint
+npm run format && npm run lint:fix
+```
+
+## Common Gotchas
+
+❌ **Don't** edit files in `swagger/composables/` - they're regenerated
+✅ **Do** edit files in `src/generators/*/runtime/` - they're your templates
+❌ **Don't** import runtime files in CLI - they run in user's Nuxt project
+✅ **Do** use `@ts-nocheck` in runtime files - different TS configs
+❌ **Don't** use `&&` in PowerShell commands - use `;` instead
+✅ **Do** test with both `useFetch` and `useAsyncData` generators
+
+---
+
+**Ready to dive deeper?** Choose your path:
+
+- 🏗️ [Understanding Architecture](./ARCHITECTURE.md) - Design patterns & decisions
+- 🔧 [Development Guide](./DEVELOPMENT.md) - Extending and contributing
+- 📖 [API Reference](./API-REFERENCE.md) - Complete technical reference
+- 🐛 [Troubleshooting](./TROUBLESHOOTING.md) - Common issues & solutions

package/docs/README.md

@@ -0,0 +1,155 @@
+# 📚 Documentation Index
+
+Welcome to the Nuxt Generator documentation! Choose your path:
+
+## 🚀 For New Developers & AI Assistants
+
+Start here if you're new to the project:
+
+- **[Quick Start Guide](./QUICK-START.md)** - Understand the project in 5 minutes
+  - What is this project?
+  - Core concepts (Two-stage generation, wrapper pattern, runtime vs build-time)
+  - Key files to read first
+  - Most common tasks
+  - Quick commands reference
+
+## 🏗️ Understanding the Codebase
+
+Learn about architecture and design decisions:
+
+- **[Architecture & Design](./ARCHITECTURE.md)** - Patterns and decisions
+  - Architectural overview
+  - Core patterns explained
+  - Design decisions (ADRs)
+  - Component dependency map
+  - Global callbacks system deep dive
+  - Extension points
+
+## 📖 Technical Reference
+
+Complete API documentation:
+
+- **[API Reference](./API-REFERENCE.md)** - Complete technical reference
+  - CLI commands
+  - Configuration options
+  - All interfaces & types
+  - Parser API
+  - Template API
+  - Runtime APIs
+  - Callback interfaces
+  - Generated composables reference
+
+## 🔧 Development & Contributing
+
+Guide for contributors:
+
+- **[Development Guide](./DEVELOPMENT.md)** - Extending and contributing
+  - Getting started
+  - Development workflow
+  - Adding new features
+  - Testing changes
+  - Code style guide
+  - Common tasks
+  - Debugging tips
+
+## 🐛 Problem Solving
+
+When things go wrong:
+
+- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues & solutions
+  - Installation problems
+  - Generation errors
+  - Runtime errors
+  - Type errors
+  - Callback issues
+  - Performance problems
+  - OpenAPI spec issues
+  - Getting help
+
+## 📋 Other Resources
+
+- **[Contributing Guidelines](../CONTRIBUTING.md)** - How to contribute code
+- **[License](../LICENSE)** - Project license
+
+## Quick Navigation by Task
+
+### "I want to understand what this project does"
+
+→ Start with [Quick Start](./QUICK-START.md#what-is-this)
+
+### "I want to know WHY it's built this way"
+
+→ Read [Architecture - Design Decisions](./ARCHITECTURE.md#design-decisions-adrs)
+
+### "I need to add a new feature"
+
+→ Follow [Development Guide - Adding Features](./DEVELOPMENT.md#adding-features)
+
+### "I'm getting an error"
+
+→ Check [Troubleshooting Guide](./TROUBLESHOOTING.md)
+
+### "I want to see all available options"
+
+→ Browse [API Reference](./API-REFERENCE.md)
+
+### "I want to understand how callbacks work"
+
+→ Read [Architecture - Global Callbacks](./ARCHITECTURE.md#global-callbacks-deep-dive)
+
+### "I want to extend the parser"
+
+→ Follow [Development - Add Parser Feature](./DEVELOPMENT.md#add-parser-feature)
+
+### "I want to add a new generator type"
+
+→ Follow [Development - Add New Generator](./DEVELOPMENT.md#add-a-new-generator-type)
+
+## Document Structure
+
+Each document is organized for different purposes:
+
+| Document        | Audience       | Purpose                        |
+| --------------- | -------------- | ------------------------------ |
+| Quick Start     | Newcomers, AI  | Fast onboarding, 5-min context |
+| Architecture    | Developers     | Understand design & patterns   |
+| API Reference   | All developers | Look up interfaces & functions |
+| Development     | Contributors   | Extend & contribute            |
+| Troubleshooting | All users      | Solve problems                 |
+
+## Glossary
+
+Quick reference for common terms:
+
+- **Two-Stage Generation**: OpenAPI → TypeScript Fetch → Nuxt Composables
+- **Wrapper Pattern**: Generated composables call runtime wrappers (useApiRequest)
+- **Runtime Files**: Code copied to user's project (not imported from npm)
+- **Build-time Runtime**: CLI tool environment (Node.js, ts-morph)
+- **User Runtime**: User's Nuxt project (Vue 3, Nuxt composables)
+- **MethodInfo**: Interface containing all data about an API endpoint
+- **Parser**: ts-morph-based code that extracts API info from TypeScript
+- **Template**: Functions that generate composable code
+- **Global Callbacks**: Callbacks defined once in plugin, apply to all requests
+- **BFF**: Backend for Frontend - pattern separating routing from business logic
+- **Raw Composables**: useAsyncData composables that return headers + status
+- **ADR**: Architectural Decision Record - documents why choices were made
+
+## Contributing to Docs
+
+Found a mistake or unclear section? Please:
+
+1. [Open an issue](https://github.com/dmartindiaz/nuxt-openapi-hyperfetch/issues) describing the problem
+2. Or submit a PR with improvements
+3. Follow the [Contributing Guide](../CONTRIBUTING.md)
+
+**Documentation Standards:**
+
+- Use clear, concise language
+- Include code examples for complex concepts
+- Link between documents for cross-references
+- Update related docs when making changes
+- Test all command examples before committing
+
+---
+
+**Ready to dive in?** Start with the [Quick Start Guide](./QUICK-START.md)!