npm - @coherent.js/koa - Versions diffs - 1.0.0-beta.3 → 1.0.0-beta.5 - Mend

@coherent.js/koa 1.0.0-beta.3 → 1.0.0-beta.5

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 (6) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,421 @@
+# @coherent.js/koa
+Koa.js adapter for Coherent.js - High-performance server-side rendering with Koa integration.
+## Installation
+```bash
+npm install @coherent.js/koa
+# or
+pnpm add @coherent.js/koa
+# or
+yarn add @coherent.js/koa
+```
+**Note:** You also need to install Koa and Coherent.js core:
+```bash
+npm install koa @coherent.js/core
+# or
+pnpm add koa @coherent.js/core
+```
+## Overview
+The `@coherent.js/koa` package provides seamless integration between Coherent.js and Koa.js, enabling you to build high-performance server-side rendered applications with Koa's middleware ecosystem.
+## Quick Start
+```javascript
+import Koa from 'koa';
+import { createCoherentHandler } from '@coherent.js/koa';
+// Create your Coherent.js component
+function App({ name = 'World' }) {
+  return {
+    div: {
+      children: [
+        { h1: { text: `Hello, ${name}!` } },
+        { p: { text: 'This is rendered with Coherent.js' } }
+      ]
+    }
+  };
+}
+// Create Koa app
+const app = new Koa();
+// Add Coherent.js handler
+app.use(createCoherentHandler(App, {
+  // Optional configuration
+  template: ({ html, head, body }) => `
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>Coherent.js Koa App</title>
+        ${head}
+      </head>
+      <body>
+        <div id="app">${body}</div>
+      </body>
+    </html>
+  `
+}));
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on http://localhost:${PORT}`);
+});
+```
+## Features
+### Middleware Integration
+Use Koa middleware alongside Coherent.js rendering:
+```javascript
+import Koa from 'koa';
+import logger from 'koa-logger';
+import { createCoherentHandler } from '@coherent.js/koa';
+const app = new Koa();
+// Add Koa middleware
+app.use(logger());
+// Add Coherent.js rendering
+app.use(createCoherentHandler(App));
+app.listen(3000);
+```
+### Request Context Access
+Access Koa request context in your components:
+```javascript
+function App({ ctx }) {
+  // ctx is the Koa context object
+  const userAgent = ctx.get('User-Agent');
+  const ipAddress = ctx.ip;
+  return {
+    div: {
+      children: [
+        { p: { text: `Your IP: ${ipAddress}` } },
+        { p: { text: `User Agent: ${userAgent}` } }
+      ]
+    }
+  };
+}
+```
+### Custom Routes
+Handle specific routes with Coherent.js:
+```javascript
+import Koa from 'koa';
+import Router from '@koa/router';
+import { createCoherentHandler } from '@coherent.js/koa';
+const app = new Koa();
+const router = new Router();
+// Handle specific routes
+router.get('/', createCoherentHandler(HomePage));
+router.get('/about', createCoherentHandler(AboutPage));
+router.get('/users/:id', createCoherentHandler(UserProfile));
+app.use(router.routes());
+app.listen(3000);
+```
+### Error Handling
+Integrate with Koa's error handling:
+```javascript
+import Koa from 'koa';
+import { createCoherentHandler } from '@coherent.js/koa';
+const app = new Koa();
+// Error handling middleware
+app.use(async (ctx, next) => {
+  try {
+    await next();
+  } catch (err) {
+    ctx.status = err.status || 500;
+    ctx.body = { error: err.message };
+    ctx.app.emit('error', err, ctx);
+  }
+});
+// Coherent.js handler
+app.use(createCoherentHandler(App));
+app.listen(3000);
+```
+## Configuration Options
+### Template Function
+Customize the HTML template:
+```javascript
+app.use(createCoherentHandler(App, {
+  template: ({ html, head, body, ctx }) => `
+    <!DOCTYPE html>
+    <html lang="${ctx.acceptsLanguages()[0] || 'en'}">
+      <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        ${head}
+      </head>
+      <body>
+        <div id="app">${body}</div>
+        <script>
+          window.__INITIAL_DATA__ = ${JSON.stringify(ctx.state)};
+        </script>
+      </body>
+    </html>
+  `
+}));
+```
+### Props Function
+Customize component props based on Koa context:
+```javascript
+app.use(createCoherentHandler(App, {
+  props: (ctx) => ({
+    userAgent: ctx.get('User-Agent'),
+    url: ctx.url,
+    user: ctx.state.user || null,
+    query: ctx.query
+  })
+}));
+```
+### Error Component
+Provide a custom error component:
+```javascript
+function ErrorPage({ error, status }) {
+  return {
+    div: {
+      className: 'error-page',
+      children: [
+        { h1: { text: `Error ${status}` } },
+        { p: { text: error.message } }
+      ]
+    }
+  };
+}
+app.use(createCoherentHandler(App, {
+  errorComponent: ErrorPage
+}));
+```
+## Performance Optimizations
+### Caching
+Enable response caching:
+```javascript
+import cache from 'koa-cache-lite';
+app.use(cache({
+  '/api/*': 5 * 60 * 1000, // 5 minutes for API routes
+  '/static/*': 60 * 60 * 1000 // 1 hour for static assets
+}));
+app.use(createCoherentHandler(App));
+```
+### Compression
+Add response compression:
+```javascript
+import compress from 'koa-compress';
+app.use(compress({
+  threshold: 2048,
+  gzip: { flush: require('zlib').constants.Z_SYNC_FLUSH }
+}));
+app.use(createCoherentHandler(App));
+```
+## Advanced Usage
+### Server-Side State Management
+Manage state during server rendering:
+```javascript
+function App({ ctx }) {
+  // Create request-scoped state
+  const requestState = {
+    requestId: Math.random().toString(36),
+    renderStartTime: Date.now()
+  };
+  ctx.state.requestState = requestState;
+  return {
+    div: {
+      children: [
+        { p: { text: `Request ID: ${requestState.requestId}` } }
+      ]
+    }
+  };
+}
+```
+### Integration with Koa Router
+Advanced routing with parameters:
+```javascript
+import Router from '@koa/router';
+const router = new Router();
+router.get('/', createCoherentHandler(HomePage));
+router.get('/users/:id', createCoherentHandler(UserProfile, {
+  props: (ctx) => ({
+    userId: ctx.params.id,
+    query: ctx.query
+  })
+}));
+router.get('/api/*', createCoherentHandler(ApiDocs));
+app.use(router.routes());
+app.use(router.allowedMethods());
+```
+## API Reference
+### createCoherentHandler(component, options)
+Create a Koa middleware for Coherent.js rendering.
+**Parameters:**
+- `component` - Coherent.js component function
+- `options.template` - Function to customize HTML template
+- `options.props` - Function to generate component props from Koa context
+- `options.errorComponent` - Component to render on errors
+- `options.enableHydration` - Boolean to enable client-side hydration (default: true)
+**Returns:** Koa middleware function
+### Options
+- `template` - Function receiving { html, head, body, ctx } and returning HTML string
+- `props` - Function receiving Koa context and returning component props
+- `errorComponent` - Component for error rendering
+- `enableHydration` - Enable/disable hydration support
+## Examples
+### Full Application Example
+```javascript
+import Koa from 'koa';
+import Router from '@koa/router';
+import bodyParser from 'koa-bodyparser';
+import logger from 'koa-logger';
+import session from 'koa-session';
+import { createCoherentHandler } from '@coherent.js/koa';
+// Components
+function HomePage({ user }) {
+  return {
+    div: {
+      children: [
+        { h1: { text: 'Welcome to Coherent.js + Koa' } },
+        user
+          ? { p: { text: `Hello, ${user.name}!` } }
+          : { a: { href: '/login', text: 'Login' } }
+      ]
+    }
+  };
+}
+function LoginPage() {
+  return {
+    form: {
+      action: '/login',
+      method: 'POST',
+      children: [
+        { input: { type: 'email', name: 'email', placeholder: 'Email' } },
+        { input: { type: 'password', name: 'password', placeholder: 'Password' } },
+        { button: { type: 'submit', text: 'Login' } }
+      ]
+    }
+  };
+}
+// Create app
+const app = new Koa();
+const router = new Router();
+// Middleware
+app.use(logger());
+app.use(bodyParser());
+app.keys = ['secret-key'];
+app.use(session(app));
+// Routes
+router.get('/', createCoherentHandler(HomePage, {
+  props: (ctx) => ({ user: ctx.session.user })
+}));
+router.get('/login', createCoherentHandler(LoginPage));
+router.post('/login', async (ctx) => {
+  // Simple auth (in production, use proper authentication)
+  const { email, password } = ctx.request.body;
+  if (email && password) {
+    ctx.session.user = { name: email.split('@')[0], email };
+    ctx.redirect('/');
+  } else {
+    ctx.status = 400;
+    ctx.body = { error: 'Invalid credentials' };
+  }
+});
+router.get('/logout', (ctx) => {
+  ctx.session = null;
+  ctx.redirect('/');
+});
+// Setup
+app.use(router.routes());
+app.use(router.allowedMethods());
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on http://localhost:${PORT}`);
+});
+```
+## Related Packages
+- [@coherent.js/core](../core/README.md) - Core framework
+- [@coherent.js/express](../express/README.md) - Express.js adapter
+- [@coherent.js/fastify](../fastify/README.md) - Fastify adapter
+- [@coherent.js/nextjs](../nextjs/README.md) - Next.js integration
+## License
+MIT

package/dist/index.cjs CHANGED Viewed

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,14 +15,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 // src/index.js
@@ -53,9 +43,9 @@ Or with yarn: yarn add ${packageName}`
 }
 // ../core/src/core/object-utils.js
-function validateComponent(component, path2 = "root") {
+function validateComponent(component, path = "root") {
   if (component === null || component === void 0) {
-    throw new Error(`Invalid component at ${path2}: null or undefined`);
+    throw new Error(`Invalid component at ${path}: null or undefined`);
   }
   if (["string", "number", "boolean"].includes(typeof component)) {
     return true;
@@ -65,31 +55,31 @@ function validateComponent(component, path2 = "root") {
   }
   if (Array.isArray(component)) {
     component.forEach((child, index) => {
-      validateComponent(child, `${path2}[${index}]`);
+      validateComponent(child, `${path}[${index}]`);
     });
     return true;
   }
   if (typeof component === "object") {
     const keys = Object.keys(component);
     if (keys.length === 0) {
-      throw new Error(`Empty object at ${path2}`);
+      throw new Error(`Empty object at ${path}`);
     }
     keys.forEach((key) => {
       const value = component[key];
       if (!/^[a-zA-Z][a-zA-Z0-9-]*$/.test(key) && key !== "text") {
-        console.warn(`Potentially invalid tag name at ${path2}: ${key}`);
+        console.warn(`Potentially invalid tag name at ${path}: ${key}`);
       }
       if (value && typeof value === "object" && !Array.isArray(value)) {
         if (value.children) {
-          validateComponent(value.children, `${path2}.${key}.children`);
+          validateComponent(value.children, `${path}.${key}.children`);
         }
       } else if (value && typeof value !== "string" && typeof value !== "number" && typeof value !== "function") {
-        throw new Error(`Invalid value type at ${path2}.${key}: ${typeof value}`);
+        throw new Error(`Invalid value type at ${path}.${key}: ${typeof value}`);
       }
     });
     return true;
   }
-  throw new Error(`Invalid component type at ${path2}: ${typeof component}`);
+  throw new Error(`Invalid component type at ${path}: ${typeof component}`);
 }
 function isCoherentObject(obj) {
   if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
@@ -171,6 +161,7 @@ function createPerformanceMonitor(options = {}) {
     },
     alerts: {
       enabled: true,
+      debounceMs: 5e3,
       rules: []
     },
     resources: {
@@ -332,7 +323,7 @@ function createPerformanceMonitor(options = {}) {
         const alertKey = `${rule.metric}-${rule.condition}-${rule.threshold}`;
         const lastTriggered = alertState.triggered.get(alertKey);
         const now = Date.now();
-        if (!lastTriggered || now - lastTriggered > 5e3) {
+        if (!lastTriggered || now - lastTriggered > opts.alerts.debounceMs) {
           alertState.triggered.set(alertKey, now);
           alertState.history.push({
             rule,
@@ -1314,107 +1305,6 @@ function createCacheManager(options = {}) {
 }
 var cacheManager = createCacheManager();
-// ../core/src/rendering/css-manager.js
-var import_promises = __toESM(require("node:fs/promises"), 1);
-var import_node_path = __toESM(require("node:path"), 1);
-var CSSManager = class {
-  constructor(options = {}) {
-    this.options = {
-      basePath: process.cwd(),
-      minify: false,
-      cache: true,
-      autoprefixer: false,
-      ...options
-    };
-    this.cache = /* @__PURE__ */ new Map();
-    this.loadedFiles = /* @__PURE__ */ new Set();
-  }
-  /**
-   * Load CSS file content
-   */
-  async loadCSSFile(filePath) {
-    const fullPath = import_node_path.default.resolve(this.options.basePath, filePath);
-    const cacheKey = fullPath;
-    if (this.options.cache && this.cache.has(cacheKey)) {
-      return this.cache.get(cacheKey);
-    }
-    try {
-      let content = await import_promises.default.readFile(fullPath, "utf8");
-      if (this.options.minify) {
-        content = this.minifyCSS(content);
-      }
-      if (this.options.cache) {
-        this.cache.set(cacheKey, content);
-      }
-      this.loadedFiles.add(filePath);
-      return content;
-    } catch (_error) {
-      console.warn(`Failed to load CSS file: ${filePath}`, _error.message);
-      return "";
-    }
-  }
-  /**
-   * Load multiple CSS files
-   */
-  async loadCSSFiles(filePaths) {
-    if (!Array.isArray(filePaths)) {
-      filePaths = [filePaths];
-    }
-    const cssContents = await Promise.all(
-      filePaths.map((filePath) => this.loadCSSFile(filePath))
-    );
-    return cssContents.join("\n");
-  }
-  /**
-   * Generate CSS link tags for external files
-   */
-  generateCSSLinks(filePaths, baseUrl = "/") {
-    if (!Array.isArray(filePaths)) {
-      filePaths = [filePaths];
-    }
-    return filePaths.map((filePath) => {
-      const href = filePath.startsWith("http") ? filePath : `${baseUrl}${filePath}`.replace(/\/+/g, "/");
-      return `<link rel="stylesheet" href="${this.escapeHtml(href)}" />`;
-    }).join("\n");
-  }
-  /**
-   * Generate inline style tag with CSS content
-   */
-  generateInlineStyles(cssContent) {
-    if (!cssContent) return "";
-    return `<style type="text/css">
-${cssContent}
-</style>`;
-  }
-  /**
-   * Basic CSS minification
-   */
-  minifyCSS(css) {
-    return css.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\s+/g, " ").replace(/;\s*}/g, "}").replace(/{\s+/g, "{").replace(/;\s+/g, ";").trim();
-  }
-  /**
-   * Escape HTML entities
-   */
-  escapeHtml(text) {
-    const div = { textContent: text };
-    return div.innerHTML || text;
-  }
-  /**
-   * Clear cache
-   */
-  clearCache() {
-    this.cache.clear();
-    this.loadedFiles.clear();
-  }
-  /**
-   * Get loaded file list
-   */
-  getLoadedFiles() {
-    return Array.from(this.loadedFiles);
-  }
-};
-var defaultCSSManager = new CSSManager();
 // ../core/src/rendering/html-renderer.js
 var rendererCache = createCacheManager({
   maxSize: 1e3,