@ozsarman/clarityjs 0.6.0

package/src/server-actions.js

@@ -0,0 +1,439 @@
+/**
+ * Clarity.js — Server Actions
+ *
+ * Type-safe client→server RPC over fetch.
+ * Similar to Next.js "use server" / React Server Actions, but framework-agnostic:
+ * any Node.js / edge runtime can host the action endpoint.
+ *
+ * ─── Server side (Node / Bun / Deno / edge) ──────────────────────────────────
+ *
+ *   // actions/user.js — mark with "use server" or defineServerAction()
+ *   import { defineServerAction } from '@ozsarman/clarityjs/server-actions';
+ *
+ *   export const createUser = defineServerAction('user/create', async ({ name, email }) => {
+ *     const user = await db.users.create({ name, email });
+ *     return { user };
+ *   });
+ *
+ *   export const deleteUser = defineServerAction('user/delete', async ({ id }) => {
+ *     await db.users.delete(id);
+ *     return { ok: true };
+ *   });
+ *
+ * ─── Server router integration ────────────────────────────────────────────────
+ *
+ *   import { createActionRouter } from '@ozsarman/clarityjs/server-actions';
+ *   import * as userActions from './actions/user.js';
+ *
+ *   const router = createActionRouter({ ...userActions });
+ *
+ *   // Express:
+ *   app.post('/_clarity/actions/:name', router.express());
+ *
+ *   // Fetch handler (edge / Bun / Deno):
+ *   export default { fetch: router.fetch() };
+ *
+ * ─── Client side (.clarity component) ───────────────────────────────────────
+ *
+ *   import { createServerClient, useServerAction } from '@ozsarman/clarityjs/server-actions';
+ *
+ *   // Create once at app root (reads CLARITY_SERVER_URL env or window.__CLARITY_SERVER__)
+ *   const server = createServerClient();
+ *
+ *   // In a component:
+ *   const { execute, loading, error, data } = useServerAction(server, 'user/create');
+ *
+ *   // Call it:
+ *   await execute({ name: 'Özdemir', email: 'oz@example.com' });
+ *   // data.get() → { user: { id: 1, name: 'Özdemir', ... } }
+ *
+ * ─── Optimistic updates ───────────────────────────────────────────────────────
+ *
+ *   const { execute } = useServerAction(server, 'todo/add', {
+ *     optimistic: (args, currentData) => [...currentData, { text: args.text, pending: true }],
+ *   });
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { signal } from './runtime.js';
+
+// ─── Server-side: action registry ────────────────────────────────────────────
+
+const _actionRegistry = new Map(); // name → handler fn
+
+/**
+ * Define a server action — registers it in the global registry with a unique name.
+ *
+ * Returns the original handler so it can also be called locally (server-to-server).
+ *
+ * @template I, O
+ * @param {string}               name    — unique action identifier (e.g. 'user/create')
+ * @param {(input: I) => Promise<O>} handler — async server function
+ * @returns {(input: I) => Promise<O>}   — the handler itself (callable directly on server)
+ */
+export function defineServerAction(name, handler) {
+  if (typeof name !== 'string' || !name.trim()) {
+    throw new TypeError('[Server Actions] name must be a non-empty string');
+  }
+  if (typeof handler !== 'function') {
+    throw new TypeError(`[Server Actions] handler for "${name}" must be a function`);
+  }
+
+  _actionRegistry.set(name, handler);
+
+  // Attach metadata so createActionRouter() can discover it
+  const fn = async (input) => handler(input);
+  fn.__serverAction__ = name;
+  fn.__handler__      = handler;
+  return fn;
+}
+
+/**
+ * List all registered server actions.
+ * @returns {string[]}
+ */
+export function listServerActions() {
+  return [..._actionRegistry.keys()];
+}
+
+// ─── Server-side: action router ───────────────────────────────────────────────
+
+/**
+ * Create an HTTP router that dispatches POST requests to registered actions.
+ *
+ * Endpoint convention:  POST /_clarity/actions/:name
+ * Request body:  JSON  { input: {...} }
+ * Response body: JSON  { data: {...} }  or  { error: 'message' }
+ *
+ * @param {...object} actionModules — spread of { [fnName]: serverActionFn } exports
+ * @returns {{ express(): Function, fetch(): Function, handle(name, input): Promise }}
+ */
+export function createActionRouter(...actionModules) {
+  // Register all passed actions
+  for (const mod of actionModules) {
+    for (const [, fn] of Object.entries(mod ?? {})) {
+      if (fn?.__serverAction__) {
+        _actionRegistry.set(fn.__serverAction__, fn.__handler__);
+      }
+    }
+  }
+
+  /**
+   * Dispatch an action by name with given input.
+   * @param {string} name
+   * @param {*}      input
+   */
+  async function handle(name, input) {
+    const handler = _actionRegistry.get(name);
+    if (!handler) {
+      const err = new Error(`Unknown server action: "${name}"`);
+      err.status = 404;
+      throw err;
+    }
+    return handler(input);
+  }
+
+  /**
+   * Express/Fastify-compatible middleware.
+   * Mount at: app.post('/_clarity/actions/:name', router.express())
+   */
+  function express() {
+    return async function clarityActionMiddleware(req, res) {
+      const name = req.params?.name ?? req.url?.split('/').pop();
+      let input;
+      try {
+        input = req.body?.input ?? req.body ?? {};
+      } catch {
+        input = {};
+      }
+
+      try {
+        const data = await handle(name, input);
+        res.json({ data });
+      } catch (err) {
+        const status = err.status ?? 500;
+        res.status(status).json({ error: err.message ?? 'Internal server error' });
+      }
+    };
+  }
+
+  /**
+   * Fetch-based handler — works in Bun, Deno, Cloudflare Workers, Vercel Edge.
+   * Mount as: export default { fetch: router.fetch() }
+   *
+   * Matches:  POST /_clarity/actions/:name
+   */
+  function fetch() {
+    return async function clarityActionFetch(request) {
+      const url = new URL(request.url);
+
+      if (request.method !== 'POST') {
+        return new Response('Method Not Allowed', { status: 405 });
+      }
+
+      const prefix = '/_clarity/actions/';
+      if (!url.pathname.startsWith(prefix)) {
+        return new Response('Not Found', { status: 404 });
+      }
+
+      const name = url.pathname.slice(prefix.length);
+      let input = {};
+      try {
+        const body = await request.json();
+        input = body?.input ?? body ?? {};
+      } catch { /* empty body */ }
+
+      try {
+        const data = await handle(name, input);
+        return Response.json({ data });
+      } catch (err) {
+        const status = err.status ?? 500;
+        return Response.json({ error: err.message ?? 'Internal server error' }, { status });
+      }
+    };
+  }
+
+  return { handle, express, fetch };
+}
+
+// ─── Client-side: server client ───────────────────────────────────────────────
+
+/**
+ * Create a typed client for calling server actions over HTTP.
+ *
+ * Reads the base URL from (in priority order):
+ *   1. opts.baseUrl
+ *   2. globalThis.__CLARITY_SERVER__
+ *   3. import.meta.env.VITE_CLARITY_SERVER_URL
+ *   4. '' (same origin — default for most setups)
+ *
+ * @param {object}  [opts]
+ * @param {string}  [opts.baseUrl]   — e.g. 'https://api.mysite.com'
+ * @param {string}  [opts.prefix]    — action endpoint prefix (default: '/_clarity/actions')
+ * @param {object}  [opts.headers]   — extra headers (e.g. auth token)
+ * @param {Function}[opts.onError]   — global error hook (err) => void
+ * @returns {ServerClient}
+ */
+export function createServerClient({
+  baseUrl = '',
+  prefix  = '/_clarity/actions',
+  headers = {},
+  onError = null,
+} = {}) {
+  // Auto-detect base URL
+  const _base = baseUrl ||
+    (typeof globalThis !== 'undefined' ? globalThis.__CLARITY_SERVER__ : '') ||
+    (typeof import.meta !== 'undefined' ? (import.meta.env?.VITE_CLARITY_SERVER_URL ?? '') : '') ||
+    '';
+
+  /**
+   * Call a server action by name.
+   *
+   * @param {string} name    — action name (e.g. 'user/create')
+   * @param {*}      input   — JSON-serializable input
+   * @returns {Promise<*>}   — resolved action output
+   */
+  async function call(name, input = {}) {
+    const url = `${_base}${prefix}/${encodeURIComponent(name)}`;
+    const res = await globalThis.fetch(url, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body:    JSON.stringify({ input }),
+    });
+
+    const json = await res.json();
+
+    if (!res.ok || json.error) {
+      const err = new Error(json.error ?? `Server action "${name}" failed (${res.status})`);
+      err.status = res.status;
+      if (typeof onError === 'function') onError(err);
+      throw err;
+    }
+
+    return json.data;
+  }
+
+  return { call, baseUrl: _base, prefix };
+}
+
+// ─── Client-side: useServerAction hook ───────────────────────────────────────
+
+/**
+ * Reactive hook for calling a server action.
+ *
+ * Returns reactive signals for loading, error, and data states.
+ * Supports optimistic updates via the `optimistic` option.
+ *
+ * @template I, O
+ * @param {ServerClient}  client     — from createServerClient()
+ * @param {string}        name       — server action name
+ * @param {object}        [opts]
+ * @param {O}             [opts.initialData]  — initial value for data signal
+ * @param {Function}      [opts.optimistic]   — (input, currentData) => O  — optimistic updater
+ * @param {Function}      [opts.onSuccess]    — (data: O) => void
+ * @param {Function}      [opts.onError]      — (err: Error) => void
+ *
+ * @returns {{
+ *   execute:  (input?: I) => Promise<O>,
+ *   loading:  Signal<boolean>,
+ *   error:    Signal<Error|null>,
+ *   data:     Signal<O|null>,
+ *   reset:    () => void,
+ * }}
+ */
+export function useServerAction(client, name, {
+  initialData = null,
+  optimistic  = null,
+  onSuccess   = null,
+  onError     = null,
+} = {}) {
+  const loading = signal(false);
+  const error   = signal(null);
+  const data    = signal(initialData);
+
+  // Snapshot of data before optimistic update (for rollback)
+  let _prevData = initialData;
+
+  async function execute(input = {}) {
+    loading.set(true);
+    error.set(null);
+
+    // Optimistic update
+    if (typeof optimistic === 'function') {
+      _prevData = data.get();
+      data.set(optimistic(input, _prevData));
+    }
+
+    try {
+      const result = await client.call(name, input);
+      data.set(result);
+      if (typeof onSuccess === 'function') onSuccess(result);
+      return result;
+    } catch (err) {
+      // Rollback optimistic update
+      if (typeof optimistic === 'function') {
+        data.set(_prevData);
+      }
+      error.set(err);
+      if (typeof onError === 'function') onError(err);
+      throw err;
+    } finally {
+      loading.set(false);
+    }
+  }
+
+  function reset() {
+    loading.set(false);
+    error.set(null);
+    data.set(initialData);
+    _prevData = initialData;
+  }
+
+  return { execute, loading, error, data, reset };
+}
+
+// ─── "use server" directive support ──────────────────────────────────────────
+
+/**
+ * Auto-register all exported server actions from a module that uses
+ * the "use server" convention.
+ *
+ * In a Clarity + Vite pipeline the compiler can insert this call automatically
+ * for any module whose first line is `'use server'`.
+ *
+ * @param {object} mod  — ES module namespace object
+ */
+export function registerServerModule(mod) {
+  for (const [, fn] of Object.entries(mod ?? {})) {
+    if (typeof fn === 'function' && fn.__serverAction__) {
+      _actionRegistry.set(fn.__serverAction__, fn.__handler__);
+    }
+  }
+}
+
+// ─── Middleware helpers ───────────────────────────────────────────────────────
+
+/**
+ * Compose multiple server action middleware functions.
+ * Each middleware receives (name, input, next) and must call next().
+ *
+ * @param {...Function} middlewares
+ * @returns {Function}  composed handler: (name, input) => Promise<*>
+ *
+ * @example
+ *   const handler = composeActionMiddleware(
+ *     authMiddleware,
+ *     logMiddleware,
+ *   );
+ *   app.post('/_clarity/actions/:name', async (req, res) => {
+ *     const data = await handler(req.params.name, req.body.input);
+ *     res.json({ data });
+ *   });
+ */
+export function composeActionMiddleware(...middlewares) {
+  return async function dispatch(name, input) {
+    let idx = -1;
+
+    async function next(i) {
+      if (i <= idx) throw new Error('[Server Actions] next() called multiple times');
+      idx = i;
+
+      if (i < middlewares.length) {
+        return middlewares[i](name, input, () => next(i + 1));
+      }
+
+      // Core dispatch
+      const handler = _actionRegistry.get(name);
+      if (!handler) {
+        const err = new Error(`Unknown server action: "${name}"`);
+        err.status = 404;
+        throw err;
+      }
+      return handler(input);
+    }
+
+    return next(0);
+  };
+}
+
+/**
+ * Built-in logging middleware — logs action name, input size, duration, and result.
+ *
+ * @param {string}   name
+ * @param {*}        input
+ * @param {Function} next
+ */
+export async function logActionMiddleware(name, input, next) {
+  const t0 = Date.now();
+  try {
+    const result = await next();
+    const ms = Date.now() - t0;
+    console.log(`[Server Action] ${name} — ${ms}ms ✓`);
+    return result;
+  } catch (err) {
+    const ms = Date.now() - t0;
+    console.error(`[Server Action] ${name} — ${ms}ms ✗ ${err.message}`);
+    throw err;
+  }
+}
+
+/**
+ * Built-in auth middleware — validates a Bearer token in headers.
+ * Inject into composeActionMiddleware() before your action logic.
+ *
+ * @param {Function} getToken   — (name, input) => string | null — extract token from context
+ * @param {Function} verify     — (token) => boolean | Promise<boolean> — validate token
+ */
+export function createAuthMiddleware(getToken, verify) {
+  return async function authMiddleware(name, input, next) {
+    const token = typeof getToken === 'function' ? getToken(name, input) : null;
+    const valid = token ? await verify(token) : false;
+    if (!valid) {
+      const err = new Error('Unauthorized');
+      err.status = 401;
+      throw err;
+    }
+    return next();
+  };
+}

package/src/server-data.js

@@ -0,0 +1,225 @@
+/**
+ * Clarity.js — Component-level SSR data fetching (`useServerData`)
+ *
+ * The companion to the file router's `loader()` export: a hook any component
+ * can call to fetch data on the server, have it serialized into the HTML, and
+ * hydrate on the client WITHOUT re-fetching. On client-side navigation (no
+ * server pass) it falls back to fetching in the browser, like SWR/createQuery.
+ *
+ *   import { useServerData } from '@ozsarman/clarityjs/server-data';
+ *
+ *   component Posts() {
+ *     const posts = useServerData('posts', () => fetch('/api/posts').then(r => r.json()));
+ *     // posts.data() · posts.loading() · posts.error() · posts.refetch()
+ *   }
+ *
+ * Render side (Express / edge):
+ *
+ *   import { renderWithServerData } from '@ozsarman/clarityjs/server-data';
+ *   const { html, state } = await renderWithServerData(Posts, props, ctx);
+ *   //  embed state into window.__CLARITY_DATA__ (renderToDocumentWithData does this)
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { signal } from './runtime.js';
+import { renderToString } from './ssr.js';
+
+// ─── SSR collection context (null in the browser) ─────────────────────────────
+// During a server render, `_ctx` holds:
+//   data    — resolved key → value map (populated on the 2nd pass)
+//   pending — [{ key, fetcher }] collected on the 1st pass
+//   keys    — every key requested (for diagnostics)
+let _ctx = null;
+
+/** @internal — begin an SSR data collection scope. */
+export function _beginServerData(data = {}) {
+  _ctx = { data, pending: [], keys: new Set() };
+  return _ctx;
+}
+
+/** @internal — end the current scope and return it. */
+export function _endServerData() {
+  const ctx = _ctx;
+  _ctx = null;
+  return ctx;
+}
+
+/** @internal — are we currently collecting on the server? */
+export function _isCollectingServerData() {
+  return _ctx !== null;
+}
+
+// ─── Hydration read (client) ──────────────────────────────────────────────────
+const SERVER_DATA_KEY = '__serverData';
+
+function _readHydrated(key) {
+  if (typeof window === 'undefined') return undefined;
+  const all = window.__CLARITY_DATA__;
+  const bag = all && all[SERVER_DATA_KEY];
+  return bag && Object.prototype.hasOwnProperty.call(bag, key) ? bag[key] : undefined;
+}
+
+// ─── Result shape ─────────────────────────────────────────────────────────────
+function _result(dataSig, loadingSig, errorSig, fetcher) {
+  const refetch = () => {
+    if (typeof fetcher !== 'function') return Promise.resolve(dataSig.get());
+    loadingSig.set(true);
+    errorSig.set(null);
+    return Promise.resolve()
+      .then(() => fetcher())
+      .then(d => { dataSig.set(d); loadingSig.set(false); return d; })
+      .catch(e => { errorSig.set(e); loadingSig.set(false); throw e; });
+  };
+
+  return {
+    // Signal-style accessors (call to read, reactive inside effects/render)
+    data:    Object.assign(() => dataSig.get(),    dataSig),
+    loading: Object.assign(() => loadingSig.get(), loadingSig),
+    error:   Object.assign(() => errorSig.get(),   errorSig),
+    refetch,
+  };
+}
+
+/**
+ * Fetch data on the server, serialize it, and hydrate it on the client.
+ *
+ * @param {string}   key       Stable key used to serialize + look up the data
+ * @param {Function} fetcher   () => value | Promise<value>  (receives the server ctx on the server)
+ * @param {object}   [options]
+ * @param {*}        [options.initialData]  Seed value before the first fetch resolves
+ * @returns {{ data, loading, error, refetch }}
+ */
+export function useServerData(key, fetcher, options = {}) {
+  const initial = options.initialData;
+
+  // ── Server path — we are inside renderWithServerData ──────────────────────
+  if (_ctx) {
+    _ctx.keys.add(key);
+    if (Object.prototype.hasOwnProperty.call(_ctx.data, key)) {
+      // 2nd pass: data resolved → seed synchronously.
+      return _result(signal(_ctx.data[key]), signal(false), signal(null), fetcher);
+    }
+    // 1st pass: register the fetcher to be awaited, render with the seed value.
+    _ctx.pending.push({ key, fetcher });
+    return _result(signal(initial), signal(true), signal(null), fetcher);
+  }
+
+  // ── Client path ───────────────────────────────────────────────────────────
+  const hydrated = _readHydrated(key);
+  if (hydrated !== undefined) {
+    // Server already fetched this — adopt it, no client fetch.
+    return _result(signal(hydrated), signal(false), signal(null), fetcher);
+  }
+
+  // No server data (client navigation / pure SPA) → fetch in the browser.
+  const dataSig    = signal(initial);
+  const loadingSig = signal(true);
+  const errorSig   = signal(null);
+  Promise.resolve()
+    .then(() => (typeof fetcher === 'function' ? fetcher() : initial))
+    .then(d => { dataSig.set(d); loadingSig.set(false); })
+    .catch(e => { errorSig.set(e); loadingSig.set(false); });
+
+  return _result(dataSig, loadingSig, errorSig, fetcher);
+}
+
+// ─── Server render orchestrator ───────────────────────────────────────────────
+
+/**
+ * Render a component to HTML, resolving every `useServerData()` call first.
+ *
+ * Two-pass strategy: render once to collect the requested keys + fetchers,
+ * await them, then render again with the resolved data. If the component uses
+ * no server data, the second pass is skipped. The resolved data is merged into
+ * `state.__serverData` so it can be embedded for client hydration.
+ *
+ * @param {Function} componentFn
+ * @param {object}   [props={}]
+ * @param {object}   [ctx={}]    Server context forwarded to each fetcher
+ * @returns {Promise<{ html, state, aiContracts, serverData }>}
+ */
+export async function renderWithServerData(componentFn, props = {}, ctx = {}) {
+  // Pass 1 — collect.
+  _beginServerData({});
+  let result, collected;
+  try {
+    result = renderToString(componentFn, props);
+  } finally {
+    collected = _endServerData();
+  }
+
+  if (!collected || collected.pending.length === 0) {
+    return { ...result, serverData: {} };
+  }
+
+  // Resolve all pending fetchers (deduped by key — last writer wins).
+  const data = {};
+  await Promise.all(
+    collected.pending.map(async ({ key, fetcher }) => {
+      data[key] = typeof fetcher === 'function' ? await fetcher(ctx) : undefined;
+    })
+  );
+
+  // Pass 2 — render with resolved data.
+  _beginServerData(data);
+  try {
+    result = renderToString(componentFn, props);
+  } finally {
+    _endServerData();
+  }
+
+  // Merge server data into the serialized state for hydration.
+  const state = { ...result.state, [SERVER_DATA_KEY]: data };
+  return { ...result, state, serverData: data };
+}
+
+/**
+ * Convenience: render a full HTML document with server data embedded into
+ * window.__CLARITY_DATA__ so client `useServerData()` calls hydrate without
+ * re-fetching.
+ *
+ * @param {Function} componentFn
+ * @param {object}   [options]
+ * @param {object}   [options.props]
+ * @param {object}   [options.ctx]
+ * @param {string}   [options.title]
+ * @param {string}   [options.lang]
+ * @param {string}   [options.clientScript]
+ * @param {string}   [options.styles]
+ * @returns {Promise<string>}
+ */
+export async function renderToDocumentWithData(componentFn, options = {}) {
+  const {
+    props = {}, ctx = {}, title = '', lang = 'en',
+    clientScript = null, styles = null,
+  } = options;
+
+  const { html, state } = await renderWithServerData(componentFn, props, ctx);
+
+  const esc = (s) => String(s ?? '').replace(/[&<>"']/g, c => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+  const stateScript = Object.keys(state).length > 0
+    ? `<script>window.__CLARITY_DATA__=${JSON.stringify(state)};</script>`
+    : '';
+  const clientTag = clientScript ? `<script type="module" src="${esc(clientScript)}"></script>` : '';
+  const styleTag  = styles ? `<style>${styles}</style>` : '';
+
+  return [
+    `<!DOCTYPE html>`,
+    `<html lang="${esc(lang)}">`,
+    `<head>`,
+    `<meta charset="utf-8">`,
+    `<meta name="viewport" content="width=device-width,initial-scale=1">`,
+    title ? `<title>${esc(title)}</title>` : '',
+    styleTag,
+    `</head>`,
+    `<body>`,
+    `<div id="app">${html}</div>`,
+    stateScript,
+    clientTag,
+    `</body>`,
+    `</html>`,
+  ].filter(Boolean).join('\n');
+}