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/README.md ADDED Viewed

@@ -0,0 +1,65 @@
+# @magneticjs/server
+Server-driven UI framework for Magnetic. Provides the JSX runtime that transforms TSX into JSON DOM descriptors, plus routing and SSR utilities.
+## Installation
+```bash
+npm install @magneticjs/server
+```
+## Usage
+### JSX Runtime (pages & components)
+```tsx
+// tsconfig.json: { "jsx": "react-jsx", "jsxImportSource": "@magneticjs/server" }
+import { Head, Link } from '@magneticjs/server/jsx-runtime';
+export function IndexPage(props: any) {
+  return (
+    <div key="app">
+      <Head><title>My App</title></Head>
+      <h1>{props.title}</h1>
+      <Link href="/about">About</Link>
+      <button onClick="do_something">Click me</button>
+    </div>
+  );
+}
+```
+### Router
+```ts
+import { createRouter } from '@magneticjs/server/router';
+const router = createRouter([
+  { path: '/', page: IndexPage },
+  { path: '/about', page: AboutPage },
+  { path: '*', page: NotFoundPage },
+]);
+const result = router.resolve('/about', viewModel);
+// → { kind: 'render', dom: DomNode }
+```
+## Key Concepts
+- **DomNode**: JSON DOM descriptor `{ tag, key?, attrs?, events?, text?, children? }`
+- **Events**: `onClick`, `onSubmit`, `onInput` → action names (strings, not callbacks)
+- **Head**: Declares `<title>` and `<meta>` tags for SSR
+- **Link**: Client-side navigation without page reload
+- **Fragment**: Groups children without a wrapper element
+## Exports
+| Path | Description |
+|------|-------------|
+| `@magneticjs/server` | Core index |
+| `@magneticjs/server/jsx-runtime` | JSX factory, Head, Link, Fragment, DomNode |
+| `@magneticjs/server/router` | createRouter, route matching |
+| `@magneticjs/server/ssr` | render_page, PageOptions |
+## License
+MIT

package/package.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "name": "@magneticjs/server",
+  "version": "0.1.0",
+  "description": "Magnetic server-driven UI framework — JSX runtime, router, SSR",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./router": "./src/router.ts",
+    "./ssr": "./src/ssr.ts"
+  },
+  "files": ["src"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": { "type": "git", "url": "https://github.com/inventhq/magnetic.git", "directory": "js/packages/magnetic-server" },
+  "homepage": "https://github.com/inventhq/magnetic#readme",
+  "keywords": ["magnetic", "server-driven-ui", "jsx", "ssr", "dom-descriptors"],
+  "license": "MIT"
+}

package/src/assets.ts ADDED Viewed

@@ -0,0 +1,190 @@
+// @magnetic/server — Static Asset Pipeline
+// Content-hashed filenames, cache headers, asset manifest
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+// ── Asset manifest ──────────────────────────────────────────────────
+export interface AssetManifest {
+  /** Maps original filename → hashed filename */
+  files: Record<string, string>;
+  /** Reverse map: hashed filename → original filename */
+  reverse: Record<string, string>;
+}
+/**
+ * Builds a content-hashed asset manifest from a source directory.
+ * Copies files to outDir with hashed names.
+ *
+ * e.g. style.css → style.a1b2c3d4.css
+ */
+export function buildAssets(opts: {
+  /** Source directory with original files */
+  srcDir: string;
+  /** Output directory for hashed files */
+  outDir: string;
+  /** File extensions to hash (default: css, js, wasm) */
+  extensions?: string[];
+  /** Files to skip hashing (served as-is) */
+  passthrough?: string[];
+}): AssetManifest {
+  const {
+    srcDir,
+    outDir,
+    extensions = ['.css', '.js', '.wasm'],
+    passthrough = [],
+  } = opts;
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  const manifest: AssetManifest = { files: {}, reverse: {} };
+  if (!existsSync(srcDir)) return manifest;
+  const entries = readdirSync(srcDir);
+  for (const entry of entries) {
+    const ext = extname(entry);
+    const srcPath = join(srcDir, entry);
+    // Passthrough files — copy without hashing
+    if (passthrough.includes(entry)) {
+      copyFileSync(srcPath, join(outDir, entry));
+      manifest.files[entry] = entry;
+      manifest.reverse[entry] = entry;
+      continue;
+    }
+    // Only hash configured extensions
+    if (!extensions.includes(ext)) {
+      copyFileSync(srcPath, join(outDir, entry));
+      manifest.files[entry] = entry;
+      manifest.reverse[entry] = entry;
+      continue;
+    }
+    // Read file and compute content hash
+    const content = readFileSync(srcPath);
+    const hash = createHash('md5').update(content).digest('hex').slice(0, 8);
+    const name = basename(entry, ext);
+    const hashedName = `${name}.${hash}${ext}`;
+    copyFileSync(srcPath, join(outDir, hashedName));
+    manifest.files[entry] = hashedName;
+    manifest.reverse[hashedName] = entry;
+  }
+  return manifest;
+}
+/**
+ * Saves manifest to a JSON file for use at runtime.
+ */
+export function saveManifest(manifest: AssetManifest, filePath: string): void {
+  writeFileSync(filePath, JSON.stringify(manifest, null, 2));
+}
+/**
+ * Loads manifest from a JSON file.
+ */
+export function loadManifest(filePath: string): AssetManifest {
+  if (!existsSync(filePath)) return { files: {}, reverse: {} };
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+// ── Asset URL resolver ──────────────────────────────────────────────
+/**
+ * Creates an asset resolver that maps original filenames to hashed URLs.
+ *
+ * Usage:
+ * ```ts
+ * const asset = createAssetResolver(manifest, '/static');
+ * asset('style.css')  // → '/static/style.a1b2c3d4.css'
+ * ```
+ */
+export function createAssetResolver(
+  manifest: AssetManifest,
+  prefix: string = '',
+): (filename: string) => string {
+  return (filename: string) => {
+    const hashed = manifest.files[filename];
+    return prefix + '/' + (hashed || filename);
+  };
+}
+// ── Serve static with cache headers ─────────────────────────────────
+export interface StaticFileResult {
+  found: boolean;
+  content?: Buffer;
+  contentType?: string;
+  headers?: Record<string, string>;
+}
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.wasm': 'application/wasm',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+};
+/**
+ * Serves a static file with appropriate cache headers.
+ * Content-hashed files get immutable cache (1 year).
+ * Non-hashed files get short cache (5 min) with revalidation.
+ */
+export function serveStatic(
+  dir: string,
+  urlPath: string,
+  manifest?: AssetManifest,
+): StaticFileResult {
+  // Strip leading slash
+  const filename = urlPath.replace(/^\//, '');
+  const filePath = join(dir, filename);
+  // Security: prevent path traversal
+  if (!filePath.startsWith(dir)) {
+    return { found: false };
+  }
+  if (!existsSync(filePath)) {
+    return { found: false };
+  }
+  const ext = extname(filename);
+  const contentType = MIME[ext] || 'application/octet-stream';
+  const content = readFileSync(filePath);
+  // Determine cache strategy
+  const isHashed = manifest?.reverse[filename] != null
+    && manifest.reverse[filename] !== filename;
+  const headers: Record<string, string> = {
+    'Content-Type': contentType,
+    'Content-Length': String(content.length),
+  };
+  if (isHashed) {
+    // Immutable — content-hashed, safe to cache forever
+    headers['Cache-Control'] = 'public, max-age=31536000, immutable';
+  } else {
+    // Short cache with revalidation
+    headers['Cache-Control'] = 'public, max-age=300, must-revalidate';
+  }
+  return { found: true, content, contentType, headers };
+}

package/src/error-boundary.ts ADDED Viewed

@@ -0,0 +1,63 @@
+// @magnetic/server — Error Boundaries
+// Wraps render/reduce in try-catch with fallback UI
+import type { DomNode } from './jsx-runtime.ts';
+export interface ErrorFallbackProps {
+  error: Error;
+  path?: string;
+  action?: string;
+}
+export type ErrorFallback = (props: ErrorFallbackProps) => DomNode;
+/** Default fallback — minimal error display */
+export const defaultFallback: ErrorFallback = ({ error, action }) => ({
+  tag: 'div',
+  key: 'error-boundary',
+  attrs: { class: 'magnetic-error' },
+  children: [
+    { tag: 'h2', key: 'err-h', text: 'Something went wrong' },
+    { tag: 'p', key: 'err-msg', text: error.message },
+    ...(action ? [{ tag: 'p', key: 'err-act', text: `Action: ${action}` }] : []),
+  ],
+});
+/**
+ * Wraps a render function with error handling.
+ * If render throws, the fallback component is returned instead.
+ */
+export function withErrorBoundary<T extends (...args: any[]) => DomNode>(
+  renderFn: T,
+  fallback: ErrorFallback = defaultFallback,
+): T {
+  return ((...args: any[]) => {
+    try {
+      return renderFn(...args);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      console.error('[magnetic] render error:', error.message);
+      return fallback({ error });
+    }
+  }) as T;
+}
+/**
+ * Wraps a reducer with error handling.
+ * If reduce throws, the original state is returned unchanged.
+ */
+export function safeReduce<S>(
+  reduceFn: (state: S, action: string, payload: any) => S,
+  onError?: (error: Error, action: string) => void,
+): (state: S, action: string, payload: any) => S {
+  return (state, action, payload) => {
+    try {
+      return reduceFn(state, action, payload);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      console.error(`[magnetic] reduce error on "${action}":`, error.message);
+      if (onError) onError(error, action);
+      return state;
+    }
+  };
+}

package/src/file-router.ts ADDED Viewed

@@ -0,0 +1,196 @@
+// @magnetic/server — File-based Router
+// Scans a pages/ directory and generates route definitions from file conventions.
+//
+// Convention:
+//   pages/
+//     index.tsx        → /
+//     about.tsx        → /about
+//     layout.tsx       → layout wrapping all routes at this level
+//     _guard.ts        → guard for all routes at this level
+//     tasks/
+//       index.tsx      → /tasks
+//       [id].tsx       → /tasks/:id
+//       layout.tsx     → layout wrapping /tasks/* routes
+//       _guard.ts      → guard for /tasks/* routes
+//
+// Exports `scanPages()` which returns a RouteDefinition[] tree.
+// This runs at build time or server startup — not at request time.
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+import type { RouteDefinition, PageComponent, LayoutComponent, RouteGuard } from './router.ts';
+export interface FileRouterOptions {
+  /** Absolute path to the pages/ directory */
+  pagesDir: string;
+  /** Function to import a module given its file path. Default: dynamic import */
+  importFn?: (filePath: string) => any;
+}
+interface ScannedModule {
+  default?: PageComponent | LayoutComponent | RouteGuard;
+  guard?: RouteGuard;
+  layout?: LayoutComponent;
+  redirect?: string;
+}
+/**
+ * Scans a pages/ directory and returns route definitions.
+ *
+ * Each .tsx file becomes a route. The default export is the page component.
+ * Special files:
+ *   - `layout.tsx` → layout component (default export)
+ *   - `_guard.ts`  → route guard (default or named `guard` export)
+ *
+ * Dynamic params use bracket syntax: `[id].tsx` → `:id`
+ */
+export function scanPages(
+  pagesDir: string,
+  modules: Record<string, ScannedModule>,
+): RouteDefinition[] {
+  if (!existsSync(pagesDir)) return [];
+  return scanDir(pagesDir, '', modules);
+}
+function scanDir(
+  dir: string,
+  pathPrefix: string,
+  modules: Record<string, ScannedModule>,
+): RouteDefinition[] {
+  const entries = readdirSync(dir).sort();
+  const routes: RouteDefinition[] = [];
+  // Check for layout and guard at this level
+  let layout: LayoutComponent | undefined;
+  let guard: RouteGuard | undefined;
+  const layoutFile = findFile(dir, 'layout');
+  if (layoutFile) {
+    const mod = modules[layoutFile];
+    if (mod) layout = (mod.default || mod.layout) as LayoutComponent;
+  }
+  const guardFile = findFile(dir, '_guard');
+  if (guardFile) {
+    const mod = modules[guardFile];
+    if (mod) guard = (mod.default || mod.guard) as RouteGuard;
+  }
+  // Scan files and subdirectories
+  const files: string[] = [];
+  const dirs: string[] = [];
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      dirs.push(entry);
+    } else if (/\.(tsx?|jsx?)$/.test(entry)) {
+      const name = basename(entry, extname(entry));
+      // Skip special files
+      if (name === 'layout' || name === '_guard') continue;
+      files.push(entry);
+    }
+  }
+  // Process page files
+  for (const file of files) {
+    const name = basename(file, extname(file));
+    const filePath = join(dir, file);
+    const mod = modules[filePath];
+    if (!mod || !mod.default) continue;
+    let segment: string;
+    if (name === 'index') {
+      segment = pathPrefix || '/';
+    } else if (name.startsWith('[') && name.endsWith(']')) {
+      // Dynamic param: [id].tsx → :id
+      const param = name.slice(1, -1);
+      segment = pathPrefix + '/:' + param;
+    } else {
+      segment = pathPrefix + '/' + name;
+    }
+    const route: RouteDefinition = {
+      path: segment,
+      page: mod.default as PageComponent,
+    };
+    if (mod.redirect) route.redirect = mod.redirect;
+    routes.push(route);
+  }
+  // Process subdirectories (nested routes)
+  for (const dirName of dirs) {
+    if (dirName.startsWith('.') || dirName === 'node_modules') continue;
+    const subDir = join(dir, dirName);
+    let segment: string;
+    if (dirName.startsWith('[') && dirName.endsWith(']')) {
+      const param = dirName.slice(1, -1);
+      segment = pathPrefix + '/:' + param;
+    } else {
+      segment = pathPrefix + '/' + dirName;
+    }
+    const children = scanDir(subDir, segment, modules);
+    if (children.length > 0) {
+      // Check if any child is the index for this path
+      const indexIdx = children.findIndex((c) => c.path === segment);
+      if (indexIdx >= 0 || layout || guard) {
+        // Create a parent route node with children
+        const parentRoute: RouteDefinition = {
+          path: segment,
+          children,
+        };
+        if (layout) parentRoute.layout = layout;
+        if (guard) parentRoute.guard = guard;
+        // If there's an index page, lift it to be the parent's page
+        if (indexIdx >= 0) {
+          parentRoute.page = children[indexIdx].page;
+          children.splice(indexIdx, 1);
+        }
+        routes.push(parentRoute);
+      } else {
+        // No layout/guard — flatten children into current level
+        routes.push(...children);
+      }
+    }
+  }
+  // If this is the root level and we have a layout/guard, wrap everything
+  if (pathPrefix === '' && (layout || guard)) {
+    return [{
+      path: '/',
+      layout,
+      guard,
+      children: routes,
+    }];
+  }
+  return routes;
+}
+function findFile(dir: string, name: string): string | null {
+  for (const ext of ['.tsx', '.ts', '.jsx', '.js']) {
+    const full = join(dir, name + ext);
+    if (existsSync(full)) return full;
+  }
+  return null;
+}
+/**
+ * Helper: converts a pages/ directory path to a route path segment.
+ * e.g. "[id]" → ":id", "about" → "about"
+ */
+export function fileNameToSegment(name: string): string {
+  if (name.startsWith('[') && name.endsWith(']')) {
+    return ':' + name.slice(1, -1);
+  }
+  return name;
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,23 @@
+// @magnetic/server — Magnetic Server Components
+// Re-exports for developer use
+export type { DomNode } from './jsx-runtime.ts';
+export { Link, Head } from './jsx-runtime.ts';
+export { createRouter, renderRoute, navigateAction } from './router.ts';
+export type { Router, RouteDefinition, RouteMatch, RouteResult, RouteGuard, PageComponent, LayoutComponent } from './router.ts';
+export { scanPages, fileNameToSegment } from './file-router.ts';
+export type { FileRouterOptions } from './file-router.ts';
+export { renderToHTML, renderPage, extractHead } from './ssr.ts';
+export type { PageOptions, ExtractedHead } from './ssr.ts';
+export { withErrorBoundary, safeReduce, defaultFallback } from './error-boundary.ts';
+export type { ErrorFallback, ErrorFallbackProps } from './error-boundary.ts';
+export { createMiddleware, createContext, loggerMiddleware, corsMiddleware, rateLimitMiddleware } from './middleware.ts';
+export type { MiddlewareStack, MiddlewareFn, MagneticContext, NextFn } from './middleware.ts';
+export { buildAssets, saveManifest, loadManifest, createAssetResolver, serveStatic } from './assets.ts';
+export type { AssetManifest, StaticFileResult } from './assets.ts';