npm package: @flightdev/edge
Description: Edge Runtime handlers for Flight Framework - deploy to any edge provider
Author: Flight Contributors
Latest version: 0.2.1

# @flightdev/edge

Edge Runtime handlers for Flight Framework. Deploy to any edge provider with a unified API.

## Philosophy

**Flight doesn't impose** - you choose your edge provider. All adapters are optional.

## Features

- **Unified geo API** - Same geo data interface across all providers
- **Cloudflare Workers** - Full cf object access, KV, R2, D1
- **Vercel Edge** - Next.js compatible middleware and routes
- **Deno Deploy** - Native Deno.serve() integration
- **Provider portable** - Switch providers without code changes
- **Zero lock-in** - Standard Request/Response objects

## Installation

```bash
npm install @flightdev/edge
```

## Quick Start

```typescript
import { createEdgeHandler } from '@flightdev/edge';

const handler = createEdgeHandler((request, ctx) => {
    const { country, city } = ctx.geo;
    
    // Fire-and-forget logging
    ctx.waitUntil(logAnalytics(request));
    
    return Response.json({ country, city });
});

export default handler;
```

## Adapters

### Cloudflare Workers

```typescript
import { createEdgeHandler } from '@flightdev/edge';
import { createCloudflareHandler } from '@flightdev/edge/cloudflare';

const handler = createEdgeHandler((req, ctx) => {
    // Full geo data from Cloudflare
    const { country, city, timezone } = ctx.geo;
    
    // Cloudflare-specific properties
    const isBot = ctx.cf?.isBot;
    const colo = ctx.cf?.colo;
    
    // Access KV, R2, D1 via env
    const kv = ctx.env?.MY_KV;
    
    return Response.json({ country, city, isBot });
});

export default createCloudflareHandler(handler);
```

### Vercel Edge

```typescript
// app/api/geo/route.ts
import { createEdgeHandler } from '@flightdev/edge';
import { createVercelHandler } from '@flightdev/edge/vercel';

const handler = createEdgeHandler((req, ctx) => {
    return Response.json({ country: ctx.geo.country });
});

export const GET = createVercelHandler(handler);
export const runtime = 'edge';
```

### Deno Deploy

```typescript
import { createEdgeHandler } from '@flightdev/edge';
import { serve } from '@flightdev/edge/deno';

const handler = createEdgeHandler((req, ctx) => {
    return new Response(`Hello from ${ctx.geo.country}!`);
});

serve(handler, { port: 8000 });
```

## EdgeContext API

```typescript
interface EdgeContext {
    // Geolocation data
    geo: {
        country?: string;   // ISO country code (AR, US, DE)
        city?: string;      // City name
        region?: string;    // Region/state
        latitude?: string;
        longitude?: string;
        timezone?: string;  // IANA timezone
    };
    
    // Cloudflare-specific (only with CF adapter)
    cf?: {
        colo?: string;      // Data center
        isBot?: boolean;
        asn?: number;
        // ... more
    };
    
    // Environment bindings
    env?: Record<string, unknown>;
    
    // Lifecycle methods
    waitUntil: (promise: Promise<unknown>) => void;
    passThroughOnException?: () => void;
}
```

## Utilities

```typescript
import {
    isEdgeRuntime,
    getEdgeRuntime,
    getGeoFromRequest,
} from '@flightdev/edge';

// Check runtime
if (isEdgeRuntime()) {
    const runtime = getEdgeRuntime(); // 'cloudflare' | 'vercel' | 'deno'
}

// Extract geo from any request
const geo = getGeoFromRequest(request);
```

## License

MIT