Simplify Method Handler Definitions

[barelyhuman]

To select between GET , POST, the user has to add an if every time which can be avoided with a simpler way to define handlers.

[traycerai]

Plan

Observations

The codebase is a Vite-based framework called adex that builds server-rendered Preact apps. Currently, API handlers in /src/api/** must export a single default function and manually check req.method with if statements to handle different HTTP methods. The issue requests simplifying this by allowing method-specific named exports like export const GET = (req, res) => {...}.

Approach

I'll implement method-specific exports by modifying the runtime handler to check for HTTP method exports (GET, POST, etc.) before falling back to the default export. This maintains backward compatibility while providing a cleaner API. The solution involves updating the handler dispatch logic, adding proper 405 error handling, and updating TypeScript definitions to support both patterns.

Reasoning

I explored the codebase structure and found that runtime/handler.js handles API route resolution and module loading. The preactPages Vite plugin discovers API files using import.meta.glob() and creates virtual modules. Currently, only the default export is called, requiring manual method checking. I examined the HTTP utilities, routing logic, and existing examples to understand the current patterns and integration points.

Proposed File Changes

📄 adex/runtime/handler.js ^(MODIFY) 🔗

Update the API handler dispatch logic to support method-specific exports. Replace the current logic that only checks for default export with a new dispatch system that:

1. First checks if the module has an export matching the HTTP method (e.g., module.GET for GET requests)
2. Falls back to module.default if no method-specific export exists (backward compatibility)
3. Returns 405 Method Not Allowed if neither exists
4. Supports common HTTP methods: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD

The new logic should be case-insensitive for the method matching and maintain the existing req.params assignment and hook emission behavior. This change occurs in the API route handling section around lines 32-44 where matchedInAPI.module() is called.

📄 adex/src/http.d.ts ^(MODIFY) 🔗

References

• 📄 adex/runtime/handler.js ^(MODIFY)

Add TypeScript definitions to support the new method-specific export pattern. Create type definitions for:

1. A Handler type that represents the (req, res) => void function signature
2. A RouteModule type that supports both the legacy default export and new method-specific exports
3. Method-specific handler types for each supported HTTP method

The types should allow developers to export either:

• export default (req, res) => {...} (legacy pattern)
• export const GET = (req, res) => {...} (new pattern)
• Or both patterns in the same file

This provides proper IntelliSense and type checking for the new API while maintaining compatibility with existing code.

📄 adex/tests/method-routing.spec.js ^(NEW) 🔗

References

• 📄 adex/tests/response-helpers.spec.js
• 📄 adex/runtime/handler.js ^(MODIFY)

Create comprehensive tests for the new method-specific routing functionality. The test suite should cover:

1. Method-specific exports: Test that GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD exports are called correctly
2. Backward compatibility: Verify that existing default export handlers continue to work
3. Fallback behavior: Test that method-specific exports take precedence over default exports
4. 405 Method Not Allowed: Verify proper error response when neither method-specific nor default export exists
5. Case sensitivity: Ensure method matching works regardless of case
6. Mixed exports: Test modules that have both default and method-specific exports

Use the existing test patterns from response-helpers.spec.js as a reference, creating mock request/response objects and testing the handler dispatch logic. Include tests for req.params assignment and hook emission to ensure existing functionality remains intact.

📄 playground/src/api/method-example.js ^(NEW) 🔗

References

• 📄 playground/src/api/hello.js
• 📄 adex/src/http.d.ts ^(MODIFY)

Create a demonstration API handler that showcases the new method-specific export pattern. This example should:

1. Export separate handlers for different HTTP methods (GET, POST, PUT, DELETE)
2. Show how each method can have different logic and response patterns
3. Demonstrate proper use of the enhanced req and res objects from adex/http
4. Include examples of JSON responses, error handling, and parameter usage
5. Serve as documentation for developers on how to use the new pattern

The example should be practical and show real-world usage patterns like:

• GET: Retrieve data
• POST: Create new resource
• PUT: Update existing resource
• DELETE: Remove resource

This provides both a working example and a test case for the new functionality in the playground environment.

📄 playground/src/api/legacy-example.js ^(NEW) 🔗

References

• 📄 playground/src/api/hello.js

Create an example that demonstrates the legacy default export pattern with manual method checking to show the "before" state that this feature improves upon. This handler should:

1. Export a single default function that manually checks req.method
2. Include if/else or switch statements for different HTTP methods
3. Show the verbose pattern that developers currently have to write
4. Include proper 405 Method Not Allowed handling
5. Demonstrate that this pattern still works (backward compatibility)

This serves as both documentation of the old pattern and a test case to ensure backward compatibility is maintained. It also helps developers understand the improvement that method-specific exports provide.

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end. Make sure you fix all the linting, compilation or validation issues after successful implementation of the plan.

### Observations

The codebase is a Vite-based framework called `adex` that builds server-rendered Preact apps. Currently, API handlers in `/src/api/**` must export a single default function and manually check `req.method` with if statements to handle different HTTP methods. The issue requests simplifying this by allowing method-specific named exports like `export const GET = (req, res) => {...}`.

### Approach

I'll implement method-specific exports by modifying the runtime handler to check for HTTP method exports (GET, POST, etc.) before falling back to the default export. This maintains backward compatibility while providing a cleaner API. The solution involves updating the handler dispatch logic, adding proper 405 error handling, and updating TypeScript definitions to support both patterns.

### Reasoning

I explored the codebase structure and found that `runtime/handler.js` handles API route resolution and module loading. The `preactPages` Vite plugin discovers API files using `import.meta.glob()` and creates virtual modules. Currently, only the `default` export is called, requiring manual method checking. I examined the HTTP utilities, routing logic, and existing examples to understand the current patterns and integration points.

## Proposed File Changes

### adex/runtime/handler.js(MODIFY)

Update the API handler dispatch logic to support method-specific exports. Replace the current logic that only checks for `default` export with a new dispatch system that:

1. First checks if the module has an export matching the HTTP method (e.g., `module.GET` for GET requests)
2. Falls back to `module.default` if no method-specific export exists (backward compatibility)
3. Returns 405 Method Not Allowed if neither exists
4. Supports common HTTP methods: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD

The new logic should be case-insensitive for the method matching and maintain the existing `req.params` assignment and hook emission behavior. This change occurs in the API route handling section around lines 32-44 where `matchedInAPI.module()` is called.

### adex/src/http.d.ts(MODIFY)

References: 

- adex/runtime/handler.js(MODIFY)

Add TypeScript definitions to support the new method-specific export pattern. Create type definitions for:

1. A `Handler` type that represents the `(req, res) => void` function signature
2. A `RouteModule` type that supports both the legacy default export and new method-specific exports
3. Method-specific handler types for each supported HTTP method

The types should allow developers to export either:
- `export default (req, res) => {...}` (legacy pattern)
- `export const GET = (req, res) => {...}` (new pattern)
- Or both patterns in the same file

This provides proper IntelliSense and type checking for the new API while maintaining compatibility with existing code.

### adex/tests/method-routing.spec.js(NEW)

References: 

- adex/tests/response-helpers.spec.js
- adex/runtime/handler.js(MODIFY)

Create comprehensive tests for the new method-specific routing functionality. The test suite should cover:

1. **Method-specific exports**: Test that `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD` exports are called correctly
2. **Backward compatibility**: Verify that existing `default` export handlers continue to work
3. **Fallback behavior**: Test that method-specific exports take precedence over default exports
4. **405 Method Not Allowed**: Verify proper error response when neither method-specific nor default export exists
5. **Case sensitivity**: Ensure method matching works regardless of case
6. **Mixed exports**: Test modules that have both default and method-specific exports

Use the existing test patterns from `response-helpers.spec.js` as a reference, creating mock request/response objects and testing the handler dispatch logic. Include tests for `req.params` assignment and hook emission to ensure existing functionality remains intact.

### playground/src/api/method-example.js(NEW)

References: 

- playground/src/api/hello.js
- adex/src/http.d.ts(MODIFY)

Create a demonstration API handler that showcases the new method-specific export pattern. This example should:

1. Export separate handlers for different HTTP methods (GET, POST, PUT, DELETE)
2. Show how each method can have different logic and response patterns
3. Demonstrate proper use of the enhanced `req` and `res` objects from `adex/http`
4. Include examples of JSON responses, error handling, and parameter usage
5. Serve as documentation for developers on how to use the new pattern

The example should be practical and show real-world usage patterns like:
- GET: Retrieve data
- POST: Create new resource
- PUT: Update existing resource
- DELETE: Remove resource

This provides both a working example and a test case for the new functionality in the playground environment.

### playground/src/api/legacy-example.js(NEW)

References: 

- playground/src/api/hello.js

Create an example that demonstrates the legacy default export pattern with manual method checking to show the "before" state that this feature improves upon. This handler should:

1. Export a single default function that manually checks `req.method`
2. Include if/else or switch statements for different HTTP methods
3. Show the verbose pattern that developers currently have to write
4. Include proper 405 Method Not Allowed handling
5. Demonstrate that this pattern still works (backward compatibility)

This serves as both documentation of the old pattern and a test case to ensure backward compatibility is maintained. It also helps developers understand the improvement that method-specific exports provide.

---

Developer Humor

Why did the HTTP handler break up with the if statement?\n> Because it found a more direct route to happiness! 🛣️\n> No more \if this, then that\ drama—\n> Just clean exports doing their job! ✨\n> GET ready for simpler code! 🚀

---

Execution Information

Branch: main
Commit: 680d36e

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.