npm - @magneticjs/server - Versions diffs - 0.1.0 - Mend

@magneticjs/server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/src/jsx-runtime.ts ADDED Viewed

@@ -0,0 +1,244 @@
+// @magnetic/server JSX runtime
+// Transforms TSX → DomNode (JSON DOM descriptors for Magnetic)
+export interface DomNode {
+  tag: string;
+  key?: string;
+  attrs?: Record<string, string>;
+  events?: Record<string, string>;
+  text?: string;
+  children?: DomNode[];
+}
+type Child = DomNode | string | number | boolean | null | undefined | Child[];
+interface Props {
+  key?: string;
+  children?: Child | Child[];
+  [prop: string]: unknown;
+}
+type Component = (props: any) => DomNode;
+// ── Built-in components ─────────────────────────────────────────────
+/**
+ * Client-side navigation link. Renders an <a> that magnetic.js intercepts
+ * to do pushState + send navigate action (no full page reload).
+ */
+export function Link(props: { href: string; children?: Child | Child[]; class?: string; [k: string]: unknown }): DomNode {
+  const { href, children, ...rest } = props;
+  return jsx('a', { ...rest, href, onClick: `navigate:${href}`, children }, undefined);
+}
+/**
+ * Declares <head> elements (title, meta, link, etc.) from within a page component.
+ * During SSR, these are extracted and placed into the document <head>.
+ * During live updates, they are ignored (head is static after SSR).
+ *
+ * Usage:
+ *   <Head><title>My Page</title><meta name="description" content="..." /></Head>
+ */
+export function Head({ children }: { children?: Child | Child[] }): DomNode {
+  const flat = flattenChildren(children);
+  return { tag: 'magnetic:head', children: flat };
+}
+// Event prop prefix → event name mapping
+const EVENT_MAP: Record<string, string> = {
+  onClick: 'click',
+  onSubmit: 'submit',
+  onInput: 'input',
+  onChange: 'change',
+  onFocus: 'focus',
+  onBlur: 'blur',
+  onKeyDown: 'keydown',
+  onKeyUp: 'keyup',
+  onScroll: 'scroll',
+};
+function flattenChildren(raw: Child | Child[]): DomNode[] {
+  if (raw == null || raw === false || raw === true) return [];
+  if (typeof raw === 'string' || typeof raw === 'number') {
+    return [{ tag: 'span', text: String(raw) }];
+  }
+  if (Array.isArray(raw)) {
+    const out: DomNode[] = [];
+    for (const c of raw) {
+      out.push(...flattenChildren(c));
+    }
+    return out;
+  }
+  return [raw as DomNode];
+}
+export function jsx(tag: string | Component, props: Props, key?: string | number): DomNode {
+  const { children, ...rest } = props;
+  // Component function — call it with props (including children)
+  if (typeof tag === 'function') {
+    return tag({ ...rest, key, children });
+  }
+  // HTML element
+  const node: DomNode = { tag };
+  if (key != null) node.key = String(key);
+  const attrs: Record<string, string> = {};
+  const events: Record<string, string> = {};
+  for (const [k, v] of Object.entries(rest)) {
+    if (v == null || v === false) continue;
+    // Event props
+    if (EVENT_MAP[k]) {
+      events[EVENT_MAP[k]] = String(v);
+      continue;
+    }
+    // class prop → attrs.class
+    if (k === 'class' || k === 'className') {
+      const cls = String(v).trim();
+      if (cls) attrs['class'] = cls;
+      continue;
+    }
+    // Boolean attributes
+    if (v === true) {
+      attrs[k] = '';
+      continue;
+    }
+    attrs[k] = String(v);
+  }
+  if (Object.keys(attrs).length) node.attrs = attrs;
+  if (Object.keys(events).length) node.events = events;
+  // Children
+  if (children != null) {
+    // Single string/number child → text property (no wrapper span)
+    if (typeof children === 'string' || typeof children === 'number') {
+      node.text = String(children);
+    } else {
+      const flat = flattenChildren(children);
+      // If all children are text spans, merge into single text
+      if (flat.length === 1 && flat[0].tag === 'span' && flat[0].text != null && !flat[0].key) {
+        node.text = flat[0].text;
+      } else if (flat.length > 0) {
+        node.children = flat;
+      }
+    }
+  }
+  return node;
+}
+// jsxs = jsx with static children array (same implementation, key is 3rd arg)
+export const jsxs = jsx;
+// Fragment — returns children as-is (for use inside other elements)
+export function Fragment({ children }: { children?: Child | Child[] }): DomNode {
+  const flat = flattenChildren(children);
+  if (flat.length === 1) return flat[0];
+  return { tag: 'div', children: flat };
+}
+// ── JSX namespace for TypeScript ────────────────────────────────────
+type Booleanish = boolean | 'true' | 'false';
+interface HtmlAttributes {
+  key?: string | number;
+  class?: string;
+  className?: string;
+  id?: string;
+  style?: string;
+  tabIndex?: number;
+  role?: string;
+  title?: string;
+  hidden?: Booleanish;
+  'data-key'?: string;
+  // Events (action names, not callbacks)
+  onClick?: string;
+  onSubmit?: string;
+  onInput?: string;
+  onChange?: string;
+  onFocus?: string;
+  onBlur?: string;
+  onKeyDown?: string;
+  onKeyUp?: string;
+  onScroll?: string;
+  children?: Child | Child[];
+  [attr: string]: unknown;
+}
+interface InputAttributes extends HtmlAttributes {
+  type?: string;
+  name?: string;
+  value?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  readonly?: boolean;
+  required?: boolean;
+  autocomplete?: string;
+  autofocus?: boolean;
+  checked?: boolean;
+}
+interface FormAttributes extends HtmlAttributes {
+  action?: string;
+  method?: string;
+  novalidate?: boolean;
+}
+export declare namespace JSX {
+  type Element = DomNode;
+  interface IntrinsicElements {
+    div: HtmlAttributes;
+    span: HtmlAttributes;
+    p: HtmlAttributes;
+    h1: HtmlAttributes;
+    h2: HtmlAttributes;
+    h3: HtmlAttributes;
+    h4: HtmlAttributes;
+    h5: HtmlAttributes;
+    h6: HtmlAttributes;
+    a: HtmlAttributes & { href?: string; target?: string; rel?: string };
+    button: HtmlAttributes & { type?: string; disabled?: boolean };
+    form: FormAttributes;
+    input: InputAttributes;
+    textarea: HtmlAttributes & { name?: string; placeholder?: string; rows?: number };
+    select: HtmlAttributes & { name?: string };
+    option: HtmlAttributes & { value?: string; selected?: boolean };
+    label: HtmlAttributes & { for?: string };
+    img: HtmlAttributes & { src?: string; alt?: string; width?: number; height?: number; loading?: string };
+    meta: HtmlAttributes & { name?: string; content?: string; property?: string; charset?: string; 'http-equiv'?: string };
+    title: HtmlAttributes;
+    link: HtmlAttributes & { rel?: string; href?: string; type?: string; sizes?: string; media?: string };
+    ul: HtmlAttributes;
+    ol: HtmlAttributes;
+    li: HtmlAttributes;
+    nav: HtmlAttributes;
+    header: HtmlAttributes;
+    footer: HtmlAttributes;
+    main: HtmlAttributes;
+    section: HtmlAttributes;
+    article: HtmlAttributes;
+    aside: HtmlAttributes;
+    strong: HtmlAttributes;
+    em: HtmlAttributes;
+    code: HtmlAttributes;
+    pre: HtmlAttributes;
+    hr: HtmlAttributes;
+    br: HtmlAttributes;
+    table: HtmlAttributes;
+    thead: HtmlAttributes;
+    tbody: HtmlAttributes;
+    tr: HtmlAttributes;
+    th: HtmlAttributes;
+    td: HtmlAttributes;
+  }
+}

package/src/middleware.ts ADDED Viewed

@@ -0,0 +1,174 @@
+// @magnetic/server — Middleware
+// Express-style use() chain with next() pattern for request processing
+import type { DomNode } from './jsx-runtime.ts';
+// ── Context ─────────────────────────────────────────────────────────
+export interface MagneticContext {
+  /** HTTP method */
+  method: string;
+  /** Request URL path */
+  path: string;
+  /** Parsed query params */
+  query: Record<string, string>;
+  /** Request headers */
+  headers: Record<string, string>;
+  /** Action name (for POST /actions/:action) */
+  action?: string;
+  /** Action payload */
+  payload?: Record<string, any>;
+  /** Attached user/session data (set by auth middleware) */
+  user?: { id: string; [key: string]: unknown };
+  /** Response status code (middleware can set this) */
+  status: number;
+  /** Response headers to add */
+  responseHeaders: Record<string, string>;
+  /** If set, short-circuit with this response body */
+  body?: string;
+  /** Arbitrary storage for middleware to share data */
+  state: Record<string, unknown>;
+}
+// ── Middleware types ─────────────────────────────────────────────────
+export type NextFn = () => void | Promise<void>;
+export type MiddlewareFn = (
+  ctx: MagneticContext,
+  next: NextFn,
+) => void | Promise<void>;
+// ── Middleware chain ─────────────────────────────────────────────────
+export interface MiddlewareStack {
+  /** Add a middleware function */
+  use(fn: MiddlewareFn): void;
+  /** Run the middleware chain for a given context */
+  run(ctx: MagneticContext): Promise<MagneticContext>;
+}
+/**
+ * Creates a middleware stack.
+ *
+ * Usage:
+ * ```ts
+ * const mw = createMiddleware();
+ * mw.use(logger);
+ * mw.use(cors);
+ * mw.use(auth);
+ * const ctx = await mw.run(context);
+ * ```
+ */
+export function createMiddleware(): MiddlewareStack {
+  const fns: MiddlewareFn[] = [];
+  return {
+    use(fn: MiddlewareFn) {
+      fns.push(fn);
+    },
+    async run(ctx: MagneticContext): Promise<MagneticContext> {
+      let index = 0;
+      async function next(): Promise<void> {
+        if (index >= fns.length) return;
+        // Short-circuit if body was set (middleware wants to respond early)
+        if (ctx.body != null) return;
+        const fn = fns[index++];
+        await fn(ctx, next);
+      }
+      await next();
+      return ctx;
+    },
+  };
+}
+// ── Helper: create context from raw request ─────────────────────────
+export function createContext(opts: {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  action?: string;
+  payload?: Record<string, any>;
+}): MagneticContext {
+  const [path, qs] = (opts.url || '/').split('?');
+  const query: Record<string, string> = {};
+  if (qs) {
+    for (const pair of qs.split('&')) {
+      const [k, v] = pair.split('=');
+      if (k) query[decodeURIComponent(k)] = decodeURIComponent(v || '');
+    }
+  }
+  return {
+    method: opts.method,
+    path,
+    query,
+    headers: opts.headers || {},
+    action: opts.action,
+    payload: opts.payload,
+    status: 200,
+    responseHeaders: {},
+    state: {},
+  };
+}
+// ── Built-in middleware ──────────────────────────────────────────────
+/** Logs request method + path + timing */
+export const loggerMiddleware: MiddlewareFn = async (ctx, next) => {
+  const start = Date.now();
+  await next();
+  const ms = Date.now() - start;
+  console.log(`[magnetic] ${ctx.method} ${ctx.path} → ${ctx.status} (${ms}ms)`);
+};
+/** CORS headers */
+export function corsMiddleware(origins: string | string[] = '*'): MiddlewareFn {
+  const origin = Array.isArray(origins) ? origins.join(', ') : origins;
+  return async (ctx, next) => {
+    ctx.responseHeaders['Access-Control-Allow-Origin'] = origin;
+    ctx.responseHeaders['Access-Control-Allow-Headers'] = 'Content-Type';
+    ctx.responseHeaders['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS';
+    if (ctx.method === 'OPTIONS') {
+      ctx.status = 204;
+      ctx.body = '';
+      return;
+    }
+    await next();
+  };
+}
+/** Rate limiter (per-IP, sliding window) */
+export function rateLimitMiddleware(opts: {
+  windowMs?: number;
+  max?: number;
+} = {}): MiddlewareFn {
+  const windowMs = opts.windowMs || 60_000;
+  const max = opts.max || 100;
+  const hits = new Map<string, { count: number; resetAt: number }>();
+  return async (ctx, next) => {
+    const ip = ctx.headers['x-forwarded-for'] || ctx.headers['x-real-ip'] || 'unknown';
+    const now = Date.now();
+    let entry = hits.get(ip);
+    if (!entry || now > entry.resetAt) {
+      entry = { count: 0, resetAt: now + windowMs };
+      hits.set(ip, entry);
+    }
+    entry.count++;
+    if (entry.count > max) {
+      ctx.status = 429;
+      ctx.body = JSON.stringify({ error: 'Too many requests' });
+      return;
+    }
+    await next();
+  };
+}

package/src/router.ts ADDED Viewed

@@ -0,0 +1,250 @@
+// @magnetic/server — Router
+// Nested routes, dynamic params, layouts, guards, redirects, file-based conventions
+import type { DomNode } from './jsx-runtime.ts';
+// ── Types ───────────────────────────────────────────────────────────
+export type PageComponent = (props: {
+  params: Record<string, string>;
+  children?: DomNode;
+  [key: string]: unknown;
+}) => DomNode;
+export type LayoutComponent = (props: {
+  children: DomNode;
+  params: Record<string, string>;
+  path: string;
+}) => DomNode;
+/** Return true to allow, a string to redirect, or { redirect } */
+export type RouteGuard = (ctx: {
+  path: string;
+  params: Record<string, string>;
+}) => true | string | { redirect: string };
+export interface RouteDefinition {
+  /** Path pattern: "/tasks/:id", "/about", "*" */
+  path: string;
+  /** Page component (leaf) */
+  page?: PageComponent;
+  /** Layout wrapping this route and its children */
+  layout?: LayoutComponent;
+  /** Guard — runs before render. Return true to allow, string to redirect */
+  guard?: RouteGuard;
+  /** Redirect target — if set, this route always redirects */
+  redirect?: string;
+  /** Nested child routes */
+  children?: RouteDefinition[];
+}
+export interface RouteMatch {
+  /** Matched page component */
+  page: PageComponent;
+  /** Extracted URL params */
+  params: Record<string, string>;
+  /** Layout chain from outermost to innermost */
+  layouts: LayoutComponent[];
+  /** Guards to run in order (outermost first) */
+  guards: RouteGuard[];
+  /** If set, this route should redirect instead of render */
+  redirect?: string;
+}
+/** Result of resolving a route — either a DomNode or a redirect */
+export type RouteResult =
+  | { kind: 'render'; dom: DomNode }
+  | { kind: 'redirect'; to: string };
+// ── Compiled route node ─────────────────────────────────────────────
+interface CompiledNode {
+  def: RouteDefinition;
+  regex: RegExp;
+  paramNames: string[];
+  children: CompiledNode[];
+}
+function compileNode(def: RouteDefinition, prefix: string): CompiledNode {
+  let pattern: string;
+  const paramNames: string[] = [];
+  if (def.path === '*') {
+    pattern = '.*';
+  } else {
+    const parts = def.path.split('/').filter(Boolean);
+    const regParts = parts.map((p) => {
+      if (p.startsWith(':')) {
+        paramNames.push(p.slice(1));
+        return '([^/]+)';
+      }
+      return p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    });
+    pattern = regParts.length ? regParts.join('/') : '';
+  }
+  const fullPattern = prefix + (pattern ? '/' + pattern : '');
+  const hasChildren = def.children && def.children.length > 0;
+  // If has children, match prefix (allow more segments after)
+  // If leaf, match exactly
+  const regexStr = hasChildren
+    ? `^${fullPattern || ''}(?:/|$)`
+    : `^${fullPattern || '/'}$`;
+  const children = (def.children || []).map((c) =>
+    compileNode(c, fullPattern)
+  );
+  return {
+    def,
+    regex: new RegExp(regexStr),
+    paramNames,
+    children,
+  };
+}
+// ── Router ──────────────────────────────────────────────────────────
+export interface Router {
+  /** Match a URL path. Returns matched page + layout chain + guards */
+  match(path: string): RouteMatch | null;
+  /** Resolve: run guards, apply redirects, nest layouts → DomNode or redirect */
+  resolve(path: string, appProps?: Record<string, unknown>): RouteResult | null;
+  /** All top-level route definitions */
+  routes: RouteDefinition[];
+}
+/**
+ * Creates a router from (potentially nested) route definitions.
+ *
+ * Supports:
+ *   - Static paths: `/about`
+ *   - Dynamic params: `/tasks/:id`
+ *   - Wildcard: `*`
+ *   - Nested routes with `children`
+ *   - Layouts at any level
+ *   - Guards at any level (run outermost first)
+ *   - Redirects (route-level or guard-returned)
+ *   - First match wins (definition order)
+ */
+export function createRouter(routes: RouteDefinition[]): Router {
+  // Compile the root as a virtual node with empty path
+  const compiled: CompiledNode[] = routes.map((r) => compileNode(r, ''));
+  function matchPath(
+    nodes: CompiledNode[],
+    path: string,
+    params: Record<string, string>,
+    layouts: LayoutComponent[],
+    guards: RouteGuard[],
+  ): RouteMatch | null {
+    const normalized = path === '/' ? '/' : path.replace(/\/+$/, '');
+    for (const node of nodes) {
+      const m = normalized.match(node.regex);
+      if (!m) continue;
+      // Extract params from this level
+      const levelParams = { ...params };
+      for (let i = 0; i < node.paramNames.length; i++) {
+        levelParams[node.paramNames[i]] = decodeURIComponent(m[i + 1]);
+      }
+      // Collect layout + guard from this level
+      const levelLayouts = node.def.layout ? [...layouts, node.def.layout] : [...layouts];
+      const levelGuards = node.def.guard ? [...guards, node.def.guard] : [...guards];
+      // Redirect at route level
+      if (node.def.redirect) {
+        return {
+          page: () => ({ tag: 'div' }),
+          params: levelParams,
+          layouts: levelLayouts,
+          guards: levelGuards,
+          redirect: node.def.redirect,
+        };
+      }
+      // Try children first (depth-first)
+      if (node.children.length > 0) {
+        const childMatch = matchPath(
+          node.children, normalized, levelParams, levelLayouts, levelGuards,
+        );
+        if (childMatch) return childMatch;
+      }
+      // Leaf match — must have a page component
+      if (node.def.page) {
+        return {
+          page: node.def.page,
+          params: levelParams,
+          layouts: levelLayouts,
+          guards: levelGuards,
+        };
+      }
+    }
+    return null;
+  }
+  return {
+    routes,
+    match(path: string): RouteMatch | null {
+      return matchPath(compiled, path, {}, [], []);
+    },
+    resolve(path: string, appProps?: Record<string, unknown>): RouteResult | null {
+      const match = this.match(path);
+      if (!match) return null;
+      // Run guards in order
+      for (const guard of match.guards) {
+        const result = guard({ path, params: match.params });
+        if (result === true) continue;
+        const to = typeof result === 'string' ? result : result.redirect;
+        return { kind: 'redirect', to };
+      }
+      // Route-level redirect
+      if (match.redirect) {
+        return { kind: 'redirect', to: match.redirect };
+      }
+      // Render page
+      const pageProps = { params: match.params, ...appProps };
+      let dom = match.page(pageProps);
+      // Wrap in layouts (innermost first → outermost wraps)
+      for (let i = match.layouts.length - 1; i >= 0; i--) {
+        dom = match.layouts[i]({ children: dom, params: match.params, path });
+      }
+      return { kind: 'render', dom };
+    },
+  };
+}
+// ── Convenience: renderRoute (backward compat) ─────────────────────
+export function renderRoute(
+  router: Router,
+  path: string,
+  appProps?: Record<string, unknown>,
+): DomNode | null {
+  const result = router.resolve(path, appProps);
+  if (!result) return null;
+  if (result.kind === 'redirect') {
+    // For backward compat, follow one redirect level
+    const r2 = router.resolve(result.to, appProps);
+    if (r2 && r2.kind === 'render') return r2.dom;
+    return null;
+  }
+  return result.dom;
+}
+// ── Navigate action string ──────────────────────────────────────────
+export function navigateAction(path: string): string {
+  return `navigate:${path}`;
+}