@ozsarman/clarityjs 0.6.0

package/src/edge.js

@@ -0,0 +1,606 @@
+/**
+ * Clarity.js — Edge Runtime
+ *
+ * Cloudflare Workers, Deno Deploy, Vercel Edge, Bun ve her türlü
+ * Web-standard Fetch API ortamında Clarity SSR + Server Actions çalıştırır.
+ *
+ * Node.js API'lerine (fs, path, stream, process) bağımlılık yoktur.
+ * Yalnızca Web standardları kullanılır:
+ *   Request, Response, URL, Headers, ReadableStream, TextEncoder, crypto
+ *
+ * ─── Kullanım (Cloudflare Workers) ──────────────────────────────────────────
+ *
+ *   import { createEdgeHandler }  from '@ozsarman/clarityjs/edge';
+ *   import { renderToString }     from '@ozsarman/clarityjs/ssr';
+ *   import App                    from './App.js';
+ *
+ *   export default createEdgeHandler({
+ *     render: (req) => renderToString(App, { url: req.url }),
+ *     actions: () => import('./actions/index.js'),
+ *   });
+ *
+ * ─── Kullanım (Vercel Edge Function) ────────────────────────────────────────
+ *
+ *   import { adaptFetchHandler }  from '@ozsarman/clarityjs/edge';
+ *   export const config = { runtime: 'edge' };
+ *   export default adaptFetchHandler(myHandler);
+ *
+ * ─── Kullanım (Deno Deploy) ─────────────────────────────────────────────────
+ *
+ *   import { createEdgeHandler } from '@ozsarman/clarityjs/edge';
+ *   Deno.serve(createEdgeHandler({ render, actions }).fetch);
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+// ─── Edge environment detection ───────────────────────────────────────────────
+
+/**
+ * Detects the current edge runtime environment.
+ * @returns {'cloudflare' | 'deno' | 'bun' | 'vercel-edge' | 'workerd' | 'node' | 'unknown'}
+ */
+export function detectEdgeRuntime() {
+  if (typeof globalThis.EdgeRuntime !== 'undefined')     return 'vercel-edge';
+  if (typeof globalThis.Deno       !== 'undefined')      return 'deno';
+  if (typeof globalThis.Bun        !== 'undefined')      return 'bun';
+  if (typeof globalThis.caches     !== 'undefined' &&
+      typeof globalThis.self       !== 'undefined' &&
+      typeof globalThis.WorkerGlobalScope !== 'undefined') return 'cloudflare';
+  if (typeof process !== 'undefined' && process.versions?.node) return 'node';
+  return 'unknown';
+}
+
+/** True when running in any Web-standard (non-Node) edge environment. */
+export const isEdgeRuntime =
+  typeof globalThis.EdgeRuntime !== 'undefined' ||
+  typeof globalThis.Deno        !== 'undefined' ||
+  typeof globalThis.Bun         !== 'undefined' ||
+  (typeof globalThis.caches     !== 'undefined' &&
+   typeof globalThis.WorkerGlobalScope !== 'undefined');
+
+// ─── Edge-compatible HTML escaping ────────────────────────────────────────────
+
+const _ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+export function escapeHTML(s) { return String(s ?? '').replace(/[&<>"']/g, c => _ESC[c]); }
+
+// ─── Edge Request wrapper ─────────────────────────────────────────────────────
+
+/**
+ * Normalize any edge/fetch Request into a plain object Clarity SSR can consume.
+ *
+ * @param {Request} req
+ * @returns {EdgeRequest}
+ */
+export function normalizeRequest(req) {
+  const url    = new URL(req.url);
+  const method = req.method.toUpperCase();
+
+  return {
+    url:      req.url,
+    method,
+    pathname: url.pathname,
+    search:   url.search,
+    query:    Object.fromEntries(url.searchParams),
+    headers:  Object.fromEntries(req.headers),
+    body:     req.body,
+
+    /** Parse JSON body (async). */
+    async json()  { return req.json(); },
+    /** Parse text body (async). */
+    async text()  { return req.text(); },
+    /** Parse FormData body (async). */
+    async form()  { return req.formData(); },
+
+    /** Get a single header (case-insensitive). */
+    header(name) { return req.headers.get(name); },
+
+    /** True when the request expects HTML (Accept: text/html). */
+    get acceptsHTML() {
+      return (req.headers.get('accept') ?? '').includes('text/html');
+    },
+
+    /** True when this looks like a Clarity Server Action call. */
+    get isAction() {
+      return method === 'POST' &&
+        url.pathname.startsWith('/_clarity/actions/');
+    },
+
+    /** Extract the action name from the URL path. */
+    get actionName() {
+      return url.pathname.replace('/_clarity/actions/', '');
+    },
+  };
+}
+
+// ─── Edge Response helpers ────────────────────────────────────────────────────
+
+/**
+ * Send an HTML response.
+ *
+ * @param {string}  html
+ * @param {object}  [opts]
+ * @param {number}  [opts.status=200]
+ * @param {object}  [opts.headers]
+ * @returns {Response}
+ */
+export function htmlResponse(html, { status = 200, headers = {} } = {}) {
+  return new Response(html, {
+    status,
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      ...headers,
+    },
+  });
+}
+
+/**
+ * Send a JSON response.
+ *
+ * @param {*}       data
+ * @param {object}  [opts]
+ * @param {number}  [opts.status=200]
+ * @param {object}  [opts.headers]
+ * @returns {Response}
+ */
+export function jsonResponse(data, { status = 200, headers = {} } = {}) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+  });
+}
+
+/**
+ * Redirect response (301 / 302 / 307 / 308).
+ *
+ * @param {string} location
+ * @param {number} [status=302]
+ * @returns {Response}
+ */
+export function redirectResponse(location, status = 302) {
+  return new Response(null, { status, headers: { Location: location } });
+}
+
+/**
+ * Streaming HTML response using ReadableStream.
+ * Useful for progressive SSR on edge runtimes that support streaming.
+ *
+ * @param {AsyncIterable<string> | ReadableStream} stream
+ * @param {object} [opts]
+ * @returns {Response}
+ */
+export function streamResponse(stream, { status = 200, headers = {} } = {}) {
+  const encoder = new TextEncoder();
+
+  const readable = stream[Symbol.asyncIterator]
+    ? new ReadableStream({
+        async start(controller) {
+          try {
+            for await (const chunk of stream) {
+              controller.enqueue(
+                typeof chunk === 'string' ? encoder.encode(chunk) : chunk
+              );
+            }
+            controller.close();
+          } catch (err) {
+            controller.error(err);
+          }
+        },
+      })
+    : stream;
+
+  return new Response(readable, {
+    status,
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Transfer-Encoding': 'chunked',
+      'X-Content-Type-Options': 'nosniff',
+      ...headers,
+    },
+  });
+}
+
+// ─── Edge-compatible SSR ──────────────────────────────────────────────────────
+
+/**
+ * Render a Clarity component to an HTML string without any Node.js APIs.
+ *
+ * Delegates to `renderToString` from ssr.js but wraps it in a try/catch
+ * with edge-compatible error formatting.
+ *
+ * @param {Function}  ComponentFn   — compiled Clarity component
+ * @param {object}    [props]
+ * @param {object}    [opts]
+ * @param {string}    [opts.title]
+ * @param {string}    [opts.lang='en']
+ * @param {string}    [opts.charset='UTF-8']
+ * @param {string[]}  [opts.scripts]    — script URLs to inject
+ * @param {string[]}  [opts.styles]     — stylesheet URLs to inject
+ * @param {string}    [opts.headExtra]  — raw HTML injected in <head>
+ * @param {string}    [opts.bodyAttr]   — extra attributes on <body>
+ * @returns {{ html: string, state: object }}
+ */
+export async function renderEdge(ComponentFn, props = {}, opts = {}) {
+  const {
+    title     = 'Clarity App',
+    lang      = 'en',
+    charset   = 'UTF-8',
+    scripts   = [],
+    styles    = [],
+    headExtra = '',
+    bodyAttr  = '',
+  } = opts;
+
+  // Minimal synchronous SSR — builds HTML without Node stream APIs
+  let bodyHTML = '';
+  let state    = {};
+
+  try {
+    // Dynamic import keeps ssr.js Node-independent in edge bundling
+    const { renderToString } = await import('./ssr.js');
+    const result = renderToString(ComponentFn, props);
+    bodyHTML = result?.html ?? String(result ?? '');
+    state    = result?.state ?? {};
+  } catch (err) {
+    // On edge we can't use process.exit(); just embed error in HTML
+    bodyHTML = `<clarity-error>${escapeHTML(err.message)}</clarity-error>`;
+  }
+
+  const styleLinks  = styles.map(href => `<link rel="stylesheet" href="${escapeHTML(href)}">`).join('\n  ');
+  const scriptTags  = scripts.map(src  => `<script type="module" src="${escapeHTML(src)}"></script>`).join('\n  ');
+  const stateScript = Object.keys(state).length > 0
+    ? `<script>window.__CLARITY_STATE__=${JSON.stringify(state)}</script>`
+    : '';
+
+  const html = `<!DOCTYPE html>
+<html lang="${escapeHTML(lang)}">
+<head>
+  <meta charset="${escapeHTML(charset)}">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHTML(title)}</title>
+  ${styleLinks}
+  ${headExtra}
+</head>
+<body${bodyAttr ? ' ' + bodyAttr : ''}>
+  <div id="app">${bodyHTML}</div>
+  ${stateScript}
+  ${scriptTags}
+</body>
+</html>`;
+
+  return { html, state };
+}
+
+// ─── Edge handler factory ─────────────────────────────────────────────────────
+
+/**
+ * Create a fully self-contained edge fetch handler.
+ *
+ * Handles:
+ *   - Server Actions  →  POST /_clarity/actions/:name
+ *   - SSR pages       →  GET  any route
+ *   - Static assets   →  GET  /assets/*, /public/* (pass-through to next handler)
+ *
+ * @param {object}    opts
+ * @param {Function}  opts.render         — async (edgeReq) => { html, state } | Response
+ * @param {Function}  [opts.actions]      — async () => actionModule (lazy import)
+ * @param {Function}  [opts.middleware]   — async (edgeReq, next) => Response
+ * @param {Function}  [opts.onError]      — (err, edgeReq) => Response
+ * @param {string[]}  [opts.staticPaths]  — prefixes to skip (e.g. ['/assets'])
+ * @param {object}    [opts.cors]         — CORS options
+ * @param {boolean}   [opts.cors.enabled=false]
+ * @param {string}    [opts.cors.origin='*']
+ * @param {string[]}  [opts.cors.methods]
+ * @returns {{ fetch: (req: Request, env?: any, ctx?: any) => Promise<Response> }}
+ */
+export function createEdgeHandler({
+  render,
+  actions,
+  middleware,
+  onError,
+  staticPaths = ['/assets/', '/public/', '/favicon', '/_next/'],
+  cors = { enabled: false, origin: '*', methods: ['GET', 'POST', 'OPTIONS'] },
+} = {}) {
+  // Lazy-loaded action registry
+  let _actionModule = null;
+
+  async function _getActions() {
+    if (!_actionModule && typeof actions === 'function') {
+      _actionModule = await actions();
+    }
+    return _actionModule ?? {};
+  }
+
+  async function _dispatchAction(name, input) {
+    const mod = await _getActions();
+
+    // Find matching action by __serverAction__ metadata or key name
+    for (const [, fn] of Object.entries(mod)) {
+      if (fn?.__serverAction__ === name || fn?.name === name) {
+        const handler = fn.__handler__ ?? fn;
+        return handler(input);
+      }
+    }
+
+    // Also check clarity-js/server-actions registry (if loaded)
+    if (typeof globalThis.__clarityActionRegistry__ !== 'undefined') {
+      const handler = globalThis.__clarityActionRegistry__.get(name);
+      if (handler) return handler(input);
+    }
+
+    const err = new Error(`Unknown server action: "${name}"`);
+    err.status = 404;
+    throw err;
+  }
+
+  async function handle(request, env, ctx) {
+    const edgeReq = normalizeRequest(request);
+
+    try {
+      // ── CORS preflight ────────────────────────────────────────────────────
+      if (cors.enabled && request.method === 'OPTIONS') {
+        return new Response(null, {
+          status: 204,
+          headers: {
+            'Access-Control-Allow-Origin':  cors.origin ?? '*',
+            'Access-Control-Allow-Methods': (cors.methods ?? ['GET','POST','OPTIONS']).join(', '),
+            'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+          },
+        });
+      }
+
+      // ── Static asset pass-through ─────────────────────────────────────────
+      for (const prefix of staticPaths) {
+        if (edgeReq.pathname.startsWith(prefix)) {
+          // Return 404 — real static serving is handled by the edge platform
+          return new Response('Not Found', { status: 404 });
+        }
+      }
+
+      // ── Optional middleware ───────────────────────────────────────────────
+      if (typeof middleware === 'function') {
+        const result = await middleware(edgeReq, async () => null);
+        if (result instanceof Response) return result;
+      }
+
+      // ── Server Actions ────────────────────────────────────────────────────
+      if (edgeReq.isAction && typeof actions !== 'undefined') {
+        const name  = edgeReq.actionName;
+        let   input = {};
+
+        try {
+          const body = await request.json();
+          input = body?.input ?? body ?? {};
+        } catch { /* empty body */ }
+
+        try {
+          const data = await _dispatchAction(name, input);
+          const res  = jsonResponse({ data });
+          if (cors.enabled) res.headers.set('Access-Control-Allow-Origin', cors.origin ?? '*');
+          return res;
+        } catch (err) {
+          const status = err.status ?? 500;
+          return jsonResponse({ error: err.message ?? 'Internal server error' }, { status });
+        }
+      }
+
+      // ── SSR render ───────────────────────────────────────────────────────
+      if (typeof render === 'function') {
+        const result = await render(edgeReq, env, ctx);
+        if (result instanceof Response) return result;
+
+        const html   = result?.html ?? String(result ?? '');
+        const status = result?.status ?? 200;
+        const res    = htmlResponse(html, { status, headers: result?.headers ?? {} });
+        if (cors.enabled) res.headers.set('Access-Control-Allow-Origin', cors.origin ?? '*');
+        return res;
+      }
+
+      return new Response('Clarity Edge Handler: no render function configured', { status: 500 });
+
+    } catch (err) {
+      if (typeof onError === 'function') {
+        const errRes = await onError(err, edgeReq);
+        if (errRes instanceof Response) return errRes;
+      }
+      return new Response(
+        `Internal Server Error: ${err.message ?? 'Unknown error'}`,
+        { status: 500, headers: { 'Content-Type': 'text/plain' } }
+      );
+    }
+  }
+
+  return {
+    /** Cloudflare Workers / Bun / Deno standard fetch handler. */
+    fetch: handle,
+    /** Vercel Edge Function default export (same signature). */
+    default: handle,
+  };
+}
+
+// ─── Vercel Edge Function adapter ────────────────────────────────────────────
+
+/**
+ * Wrap any `(req: Request) => Response | Promise<Response>` function
+ * for Vercel Edge Function deployment.
+ *
+ * @param {Function} handler
+ * @param {object}   [config]   — Vercel edge config (runtime, regions, etc.)
+ * @returns {{ default: Function, config: object }}
+ */
+export function adaptFetchHandler(handler, config = {}) {
+  return {
+    default: (req) => handler(req),
+    config:  { runtime: 'edge', ...config },
+  };
+}
+
+// ─── Edge KV / Cache helpers ──────────────────────────────────────────────────
+
+/**
+ * Edge-compatible in-memory cache (falls back to platform KV when available).
+ * Works across Cloudflare Workers (caches API), Deno KV, Vercel Edge cache.
+ *
+ * @param {string} [namespace='clarity']
+ * @returns {EdgeCache}
+ */
+export function createEdgeCache(namespace = 'clarity') {
+  // In-memory fallback (per-request in stateless workers, longer in Deno/Bun)
+  const _mem = new Map();
+
+  return {
+    /**
+     * Get a cached value.
+     * @param {string}  key
+     * @returns {Promise<string | null>}
+     */
+    async get(key) {
+      const fullKey = `${namespace}:${key}`;
+
+      // Cloudflare Workers cache API
+      if (typeof caches !== 'undefined') {
+        try {
+          const cache = await caches.open(namespace);
+          const res   = await cache.match(new Request(`https://clarity-cache/${fullKey}`));
+          if (res) return res.text();
+        } catch { /* fall through to memory */ }
+      }
+
+      // Deno KV
+      if (typeof globalThis.Deno?.openKv === 'function') {
+        try {
+          const kv     = await globalThis.Deno.openKv();
+          const result = await kv.get([namespace, key]);
+          return result.value ?? null;
+        } catch { /* fall through */ }
+      }
+
+      return _mem.get(fullKey) ?? null;
+    },
+
+    /**
+     * Set a cached value.
+     * @param {string}  key
+     * @param {string}  value
+     * @param {number}  [ttl]  — seconds
+     */
+    async set(key, value, ttl) {
+      const fullKey = `${namespace}:${key}`;
+
+      if (typeof caches !== 'undefined') {
+        try {
+          const cache = await caches.open(namespace);
+          const res   = new Response(value, {
+            headers: ttl
+              ? { 'Cache-Control': `max-age=${ttl}` }
+              : {},
+          });
+          await cache.put(new Request(`https://clarity-cache/${fullKey}`), res);
+          return;
+        } catch { /* fall through */ }
+      }
+
+      if (typeof globalThis.Deno?.openKv === 'function') {
+        try {
+          const kv   = await globalThis.Deno.openKv();
+          const opts = ttl ? { expireIn: ttl * 1000 } : undefined;
+          await kv.set([namespace, key], value, opts);
+          return;
+        } catch { /* fall through */ }
+      }
+
+      _mem.set(fullKey, value);
+      if (ttl) setTimeout(() => _mem.delete(fullKey), ttl * 1000);
+    },
+
+    /** Delete a cached key. */
+    async delete(key) {
+      const fullKey = `${namespace}:${key}`;
+
+      if (typeof caches !== 'undefined') {
+        try {
+          const cache = await caches.open(namespace);
+          await cache.delete(new Request(`https://clarity-cache/${fullKey}`));
+        } catch { /* fall through */ }
+      }
+
+      _mem.delete(fullKey);
+    },
+  };
+}
+
+// ─── Edge geolocation helper ──────────────────────────────────────────────────
+
+/**
+ * Extract geolocation from edge request headers.
+ * Reads Cloudflare, Vercel, and Fastly geo headers.
+ *
+ * @param {Request} req
+ * @returns {{ country: string, city: string, region: string, timezone: string }}
+ */
+export function getGeo(req) {
+  const h = (name) => req.headers.get(name) ?? '';
+
+  return {
+    country:  h('cf-ipcountry') || h('x-vercel-ip-country') || h('x-country') || '',
+    city:     h('cf-ipcity')    || h('x-vercel-ip-city')    || h('x-city')    || '',
+    region:   h('cf-region')    || h('x-vercel-ip-country-region') || '',
+    timezone: h('cf-timezone')  || h('x-vercel-ip-timezone') || '',
+    ip:       h('cf-connecting-ip') || h('x-real-ip') || h('x-forwarded-for').split(',')[0] || '',
+    latitude: h('cf-iplongitude') || '',
+    longitude:h('cf-iplatitude')  || '',
+  };
+}
+
+// ─── Edge environment variable access ────────────────────────────────────────
+
+/**
+ * Get an environment variable in any edge runtime.
+ * Cloudflare: env object passed to fetch handler.
+ * Deno: Deno.env.get()
+ * Bun / Node: process.env
+ *
+ * @param {string}  key
+ * @param {object}  [env]   — Cloudflare env object (from fetch handler 2nd arg)
+ * @param {string}  [fallback]
+ * @returns {string | undefined}
+ */
+export function getEnv(key, env, fallback) {
+  if (env && typeof env[key] !== 'undefined') return env[key];
+  if (typeof globalThis.Deno !== 'undefined') return globalThis.Deno.env.get(key) ?? fallback;
+  if (typeof process !== 'undefined')         return process.env[key] ?? fallback;
+  return fallback;
+}
+
+// ─── Edge-compatible crypto ───────────────────────────────────────────────────
+
+/**
+ * Generate a random ID using Web Crypto (available in all edge runtimes).
+ * @param {number} [bytes=16]
+ * @returns {string}  hex string
+ */
+export function randomId(bytes = 16) {
+  const buf = new Uint8Array(bytes);
+  (globalThis.crypto ?? crypto).getRandomValues(buf);
+  return Array.from(buf, b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * HMAC-SHA256 signature (Web Crypto — works on all edges).
+ *
+ * @param {string} secret
+ * @param {string} message
+ * @returns {Promise<string>}  hex digest
+ */
+export async function hmacSign(secret, message) {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw', enc.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false, ['sign']
+  );
+  const sig = await crypto.subtle.sign('HMAC', key, enc.encode(message));
+  return Array.from(new Uint8Array(sig), b => b.toString(16).padStart(2, '0')).join('');
+}