@objectql/edge-adapter

Edge runtime adapter for ObjectQL — runtime detection, capability validation, and driver binding resolution.

Features

🌐 Runtime Detection

• Automatic detection of Cloudflare Workers, Deno Deploy, Vercel Edge, Bun, and Node.js
• Inspection of global objects with ordered specificity to avoid false positives

✅ Capability Validation

• Validate runtime capabilities (WASM, persistent storage, WebSocket, scheduled triggers)
• Enforce minimum execution time requirements
• Pre-flight checks before driver initialization

🔌 Driver Binding Resolution

• Automatic driver selection per runtime (e.g., @objectql/driver-sqlite-wasm for Cloudflare Workers)
• Explicit binding overrides for custom datasource configurations
• Default fallback bindings when no explicit config is provided

⚡ Plugin Integration

• Implements RuntimePlugin for seamless kernel integration
• Registers edge context (runtime, capabilities, bindings) on the kernel
• Request-scoped connection support for stateless environments

Installation

pnpm add @objectql/edge-adapter

Quick Start

import { EdgeAdapterPlugin } from '@objectql/edge-adapter';
import { createKernel } from '@objectstack/runtime';

const kernel = createKernel({
  plugins: [
    new EdgeAdapterPlugin({
      // Auto-detect runtime (or override manually)
      // runtime: 'cloudflare-workers',
      requirements: {
        wasm: true,
        persistentStorage: true,
      },
    })
  ]
});

await kernel.start();

Runtime Detection

The detectRuntime() function inspects globalThis to determine the current edge runtime.

import { detectRuntime } from '@objectql/edge-adapter';

const runtime = detectRuntime();
// => 'cloudflare-workers' | 'deno-deploy' | 'vercel-edge' | 'bun' | 'node'

Detection order (most specific first):

| Runtime | Detection Signal | |----------------------|-------------------------------------------| | Cloudflare Workers | globalThis.caches + globalThis.WebSocketPair | | Deno Deploy | globalThis.Deno | | Bun | globalThis.Bun | | Vercel Edge | globalThis.EdgeRuntime | | Node.js | Default fallback |

Capability Validation

Validate that the detected runtime meets your application requirements before initialization.

import { detectRuntime, validateCapabilities, getCapabilities } from '@objectql/edge-adapter';

const runtime = detectRuntime();
const capabilities = getCapabilities(runtime);

console.log(capabilities);
// { wasm: true, persistentStorage: true, webSocket: true, ... }

const validation = validateCapabilities(runtime, {
  wasm: true,
  persistentStorage: true,
  minExecutionTime: 30000,
});

if (!validation.valid) {
  console.error('Missing capabilities:', validation.missing);
}

CapabilityRequirement

| Property | Type | Description | |----------------------|-----------|-------------------------------------------| | wasm | boolean | Requires WebAssembly support | | persistentStorage | boolean | Requires persistent storage (KV, D1, etc.)| | webSocket | boolean | Requires WebSocket support | | scheduledTriggers | boolean | Requires scheduled/cron trigger support | | minExecutionTime | number | Minimum execution time in milliseconds |

Driver Binding Configuration

Each runtime has a recommended default driver. You can override bindings explicitly.

import { EdgeAdapterPlugin } from '@objectql/edge-adapter';

const plugin = new EdgeAdapterPlugin({
  runtime: 'cloudflare-workers',
  bindings: {
    default: {
      driver: '@objectql/driver-sqlite-wasm',
      binding: 'DB',
      config: { pragma: { journal_mode: 'WAL' } },
    },
    cache: {
      driver: '@objectql/driver-memory',
      config: { maxSize: 1000 },
    },
  },
});

Default Driver Bindings

| Runtime | Default Driver | |----------------------|---------------------------------| | Cloudflare Workers | @objectql/driver-sqlite-wasm | | Deno Deploy | @objectql/driver-pg-wasm | | Vercel Edge | @objectql/driver-memory | | Bun | @objectql/driver-sqlite-wasm | | Node.js | @objectql/driver-sql |

API Reference

Functions

| Function | Description | |------------------------|------------------------------------------------------| | detectRuntime() | Returns the detected EdgeRuntime string | | getCapabilities(rt) | Returns the EdgeCapabilities for a given runtime | | validateCapabilities(rt, req) | Validates a runtime against CapabilityRequirement | | getDefaultDriver(rt) | Returns the recommended driver package name | | resolveBindings(cfg) | Resolves ResolvedBinding[] from EdgeAdapterConfig |

Classes

| Class | Description | |------------------------|------------------------------------------------------| | EdgeAdapterPlugin | RuntimePlugin — detects runtime, validates, binds |

Types

| Type | Description | |-------------------------------|-----------------------------------------------| | EdgeAdapterPluginConfig | Plugin constructor options | | CapabilityRequirement | Minimum capability requirements | | CapabilityValidationResult | Result of validateCapabilities() | | ResolvedBinding | Resolved driver binding for a datasource |

License

MIT