@maravilla-labs/functions/README.md

Maravilla Edge Functions bundler and development tools

# @maravilla-labs/functions

Maravilla Edge Functions bundler and development tools. This package provides esbuild-based bundling for edge functions, transforming multiple JavaScript function files into a single optimized bundle for WASM execution.

## Installation

```bash
npm install --save-dev @maravilla-labs/functions
```

## Usage

### CLI Commands

```bash
# Build functions for production
npx maravilla-functions build

# Build with options
npx maravilla-functions build --output dist --minify --sourcemap

# Start development mode with file watching
npx maravilla-functions dev

# Development mode with custom output
npx maravilla-functions dev --output build
```

### Package.json Scripts

Add to your `functions/package.json`:

```json
{
  "scripts": {
    "build": "maravilla-functions build",
    "dev": "maravilla-functions dev",
    "build:prod": "maravilla-functions build --minify"
  },
  "devDependencies": {
  "@maravilla-labs/functions": "latest"
  }
}
```

### Function Structure

Functions should be organized in a flat or nested structure:

```
functions/
├── package.json
├── hello.js
├── user-profile.js
└── auth/
    └── login.js
```

Each function file should export HTTP method handlers:

```javascript
// hello.js
export const GET = (request, response) => {
  response.json({ message: 'Hello World!' });
};

export const POST = (request, response) => {
  const body = JSON.parse(request.body || '{}');
  response.json({ received: body });
};
```

### Route Mapping

Functions are automatically mapped to API routes:

- `hello.js` → `/api/hello`
- `user-profile.js` → `/api/user-profile`
- `auth/login.js` → `/api/auth/login`

### HTTP Methods

Supported export patterns:

```javascript
// Named method exports
export const GET = (request, response) => { /* ... */ };
export const POST = (request, response) => { /* ... */ };
export const PUT = (request, response) => { /* ... */ };
export const DELETE = (request, response) => { /* ... */ };

// Default export handles all methods
export default (request, response) => {
  // Handle based on request.method
};
```

### Request Object

```javascript
{
  method: 'GET',           // HTTP method
  url: 'http://...',       // Full URL
  path: '/api/hello',      // Path part
  query: { id: '123' },    // Query parameters as object
  headers: { ... },        // Headers as object
  body: '...'              // Raw body string
}
```

### Response Object

```javascript
response.status(200)                    // Set status code
response.setHeader('key', 'value')      // Set header
response.json({ data: 'value' })        // JSON response
response.text('plain text')             // Text response
response.html('<h1>HTML</h1>')          // HTML response
```

## Build Output

The bundler generates:

- `dist/functions.js` - Single bundled JavaScript file
- Source maps (if enabled)
- Minified output (if enabled)

The bundle includes:

- All function modules with proper ES6 imports
- Runtime helpers (Request/Response classes)
- Route registry for path matching
- Global `handleRequest` function for WASM integration

## Integration with Maravilla CLI

The Maravilla CLI automatically detects and uses the bundled output:

1. Looks for `functions/dist/functions.js`
2. Compiles to QuickJS bytecode
3. Embeds in WASM runtime
4. Serves via HTTP with automatic routing

## Development Workflow

1. **Setup functions directory:**
   ```bash
   mkdir functions
   cd functions
   npm init -y
  npm install --save-dev @maravilla-labs/functions
   ```

2. **Add build scripts:**
   ```json
   {
     "scripts": {
       "build": "maravilla-functions build",
       "dev": "maravilla-functions dev"
     }
   }
   ```

3. **Create function files:**
   ```javascript
   // hello.js
   export const GET = (request, response) => {
     response.json({ message: 'Hello from Maravilla!' });
   };
   ```

4. **Build and serve:**
   ```bash
   npm run build
   maravilla serve --dev --framework-port 5173
   ```

## Features

- ✅ **esbuild-powered** - Fast, reliable bundling
- ✅ **ES6 modules** - Native import/export support
- ✅ **File watching** - Automatic rebuilds in dev mode
- ✅ **Source maps** - Debug support
- ✅ **Minification** - Production optimization
- ✅ **Route mapping** - Automatic API route generation
- ✅ **Method detection** - HTTP method analysis
- ✅ **WASM integration** - Seamless CLI integration

## License

Proprietary. © 2025 SOLUTAS GmbH, Switzerland. All rights reserved.
Use is governed by the root LICENSE file or a separate written agreement
with SOLUTAS GmbH.