@coherent.js/express 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Drouvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @coherent.js/express
+
+[![npm version](https://img.shields.io/npm/v/@coherent.js/express.svg)](https://www.npmjs.com/package/@coherent.js/express)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+[![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+
+Express adapter for Coherent.js.
+
+- ESM-only, Node 20+
+- Works with `express@4.x`
+- Designed to pair with `@coherent.js/core`
+
+For a high-level overview and repository-wide instructions, see the root README: ../../README.md
+
+## Installation
+
+```bash
+pnpm add @coherent.js/express express @coherent.js/core
+```
+
+Peer dependencies:
+- `express` >= 4.18 < 6
+- `@coherent.js/core`
+
+## Quick start
+
+You can use `@coherent.js/core` rendering inside Express handlers.
+
+JavaScript (ESM):
+```js
+import express from 'express';
+import { renderToString } from '@coherent.js/core';
+
+const app = express();
+
+app.get('/', async (_req, res) => {
+  const html = await renderToString({ div: { text: 'Hello from Express + Coherent' } });
+  res.type('html').send(html);
+});
+
+app.listen(3000, () => console.log('http://localhost:3000'));
+```
+
+TypeScript:
+```ts
+import express, { Request, Response } from 'express';
+import { renderToString } from '@coherent.js/core';
+
+const app = express();
+
+app.get('/', async (_req: Request, res: Response) => {
+  const html = await renderToString({ div: { text: 'Hello TS' } });
+  res.type('html').send(html);
+});
+
+app.listen(3000);
+```
+
+## Development
+
+```bash
+pnpm --filter @coherent.js/express run test
+pnpm --filter @coherent.js/express run test:watch
+pnpm --filter @coherent.js/express run typecheck
+pnpm --filter @coherent.js/express run build
+```
+
+## License
+
+MIT © Coherent.js Team

package/dist/express/coherent-express.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Coherent.js Express middleware
+ * Automatically renders Coherent.js components and handles errors
+ *
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.enablePerformanceMonitoring - Enable performance monitoring
+ * @param {string} options.template - HTML template with {{content}} placeholder
+ * @returns {Function} Express middleware function
+ */
+export function coherentMiddleware(options?: {
+    enablePerformanceMonitoring: boolean;
+    template: string;
+}): Function;
+/**
+ * Create an Express route handler for Coherent.js components
+ *
+ * @param {Function} componentFactory - Function that returns a Coherent.js component
+ * @param {Object} options - Handler options
+ * @returns {Function} Express route handler
+ */
+export function createCoherentHandler(componentFactory: Function, options?: Object): Function;
+/**
+ * Enhanced Express engine for Coherent.js views
+ *
+ * @param {string} filePath - Path to view file (not used in Coherent.js)
+ * @param {Object} options - View options containing Coherent.js component
+ * @param {Function} callback - Callback function
+ */
+export function enhancedExpressEngine(filePath: string, options: Object, callback: Function): void;
+/**
+ * Setup Coherent.js with Express app
+ *
+ * @param {Object} app - Express app instance
+ * @param {Object} options - Setup options
+ */
+export function setupCoherentExpress(app: Object, options?: Object): void;
+/**
+ * Create Express integration with dependency checking
+ * This function ensures Express is available before setting up the integration
+ *
+ * @param {Object} options - Setup options
+ * @returns {Promise<Function>} - Function to setup Express integration
+ */
+export function createExpressIntegration(options?: Object): Promise<Function>;
+declare namespace _default {
+    export { coherentMiddleware };
+    export { createCoherentHandler };
+    export { enhancedExpressEngine };
+    export { setupCoherentExpress };
+    export { createExpressIntegration };
+}
+export default _default;
+//# sourceMappingURL=coherent-express.d.ts.map

package/dist/express/coherent-express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coherent-express.d.ts","sourceRoot":"","sources":["../../../../src/express/coherent-express.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH,6CAJG;IAAyB,2BAA2B,EAA5C,OAAO;IACS,QAAQ,EAAxB,MAAM;CACd,YA6CF;AAkBD;;;;;;GAMG;AACH,4EAHW,MAAM,YAyChB;AAED;;;;;;GAMG;AACH,gDAJW,MAAM,WACN,MAAM,4BAWhB;AAED;;;;;GAKG;AACH,0CAHW,MAAM,YACN,MAAM,QAoBhB;AAED;;;;;;GAMG;AACH,mDAHW,MAAM,GACJ,OAAO,UAAU,CAkB7B"}

package/dist/express/coherent-express.js

@@ -0,0 +1,171 @@
+/**
+ * Enhanced Express.js integration for Coherent.js
+ * Provides middleware and utilities for using Coherent.js with Express
+ */
+import { renderToString, renderHTML } from '../rendering/html-renderer.js';
+import { performanceMonitor } from '../performance/monitor.js';
+import { importPeerDependency } from '../utils/dependency-utils.js';
+/**
+ * Coherent.js Express middleware
+ * Automatically renders Coherent.js components and handles errors
+ *
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.enablePerformanceMonitoring - Enable performance monitoring
+ * @param {string} options.template - HTML template with {{content}} placeholder
+ * @returns {Function} Express middleware function
+ */
+export function coherentMiddleware(options = {}) {
+    const { enablePerformanceMonitoring = false, template = '<!DOCTYPE html>\n{{content}}' } = options;
+    return (req, res, next) => {
+        // Store original send method
+        const originalSend = res.send;
+        // Override send method to handle Coherent.js objects
+        res.send = function (data) {
+            // If data is a Coherent.js object (plain object with a single key), render it
+            if (isCoherentObject(data)) {
+                try {
+                    let html;
+                    if (enablePerformanceMonitoring) {
+                        const renderId = performanceMonitor.startRender();
+                        html = renderToString(data);
+                        performanceMonitor.endRender(renderId);
+                    }
+                    else {
+                        html = renderToString(data);
+                    }
+                    // Apply template
+                    const finalHtml = template.replace('{{content}}', html);
+                    // Set content type and send HTML
+                    res.set('Content-Type', 'text/html');
+                    return originalSend.call(this, finalHtml);
+                }
+                catch (error) {
+                    console.error('Coherent.js rendering error:', error);
+                    return next(error);
+                }
+            }
+            // For non-Coherent.js data, use original send method
+            return originalSend.call(this, data);
+        };
+        next();
+    };
+}
+/**
+ * Check if an object is a Coherent.js component object
+ * A Coherent.js component is a plain object with a single key
+ *
+ * @param {any} obj - Object to check
+ * @returns {boolean} True if object is a Coherent.js component
+ */
+function isCoherentObject(obj) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        return false;
+    }
+    const keys = Object.keys(obj);
+    return keys.length === 1;
+}
+/**
+ * Create an Express route handler for Coherent.js components
+ *
+ * @param {Function} componentFactory - Function that returns a Coherent.js component
+ * @param {Object} options - Handler options
+ * @returns {Function} Express route handler
+ */
+export function createCoherentHandler(componentFactory, options = {}) {
+    const { enablePerformanceMonitoring = false, template = '<!DOCTYPE html>\n{{content}}' } = options;
+    return async (req, res, next) => {
+        try {
+            // Create component with request data
+            const component = await Promise.resolve(componentFactory(req, res, next));
+            if (!component) {
+                return next(new Error('Component factory returned null/undefined'));
+            }
+            // Render component
+            let html;
+            if (enablePerformanceMonitoring) {
+                const renderId = performanceMonitor.startRender();
+                html = renderToString(component);
+                performanceMonitor.endRender(renderId);
+            }
+            else {
+                html = renderToString(component);
+            }
+            // Apply template
+            const finalHtml = template.replace('{{content}}', html);
+            // Send HTML response
+            res.set('Content-Type', 'text/html');
+            res.send(finalHtml);
+        }
+        catch (error) {
+            console.error('Coherent.js handler error:', error);
+            next(error);
+        }
+    };
+}
+/**
+ * Enhanced Express engine for Coherent.js views
+ *
+ * @param {string} filePath - Path to view file (not used in Coherent.js)
+ * @param {Object} options - View options containing Coherent.js component
+ * @param {Function} callback - Callback function
+ */
+export function enhancedExpressEngine(filePath, options, callback) {
+    try {
+        // Render Coherent.js component from options
+        const html = renderHTML(options);
+        callback(null, html);
+    }
+    catch (error) {
+        callback(error);
+    }
+}
+/**
+ * Setup Coherent.js with Express app
+ *
+ * @param {Object} app - Express app instance
+ * @param {Object} options - Setup options
+ */
+export function setupCoherentExpress(app, options = {}) {
+    const { useMiddleware = true, useEngine = true, engineName = 'coherent', enablePerformanceMonitoring = false } = options;
+    // Register enhanced engine
+    if (useEngine) {
+        app.engine(engineName, enhancedExpressEngine);
+        app.set('view engine', engineName);
+    }
+    // Use middleware for automatic rendering
+    if (useMiddleware) {
+        app.use(coherentMiddleware({ enablePerformanceMonitoring }));
+    }
+}
+/**
+ * Create Express integration with dependency checking
+ * This function ensures Express is available before setting up the integration
+ *
+ * @param {Object} options - Setup options
+ * @returns {Promise<Function>} - Function to setup Express integration
+ */
+export async function createExpressIntegration(options = {}) {
+    try {
+        // Verify Express is available
+        await importPeerDependency('express', 'Express.js');
+        return function (app) {
+            if (!app || typeof app.use !== 'function') {
+                throw new Error('Invalid Express app instance provided');
+            }
+            setupCoherentExpress(app, options);
+            return app;
+        };
+    }
+    catch (error) {
+        throw error;
+    }
+}
+// Export all utilities
+export default {
+    coherentMiddleware,
+    createCoherentHandler,
+    enhancedExpressEngine,
+    setupCoherentExpress,
+    createExpressIntegration
+};
+//# sourceMappingURL=coherent-express.js.map

package/dist/express/coherent-express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coherent-express.js","sourceRoot":"","sources":["../../../../src/express/coherent-express.js"],"names":[],"mappings":"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"}

package/dist/express/index.d.ts

@@ -0,0 +1,3 @@
+export function expressEngine(): (filePath: any, options: any, callback: any) => void;
+export function setupCoherent(app: any): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/express/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/express/index.js"],"names":[],"mappings":"AAGA,kCACY,aAAQ,EAAE,YAAO,EAAE,aAAQ,UAStC;AAGD,8CAGC"}

package/dist/express/index.js

@@ -0,0 +1,20 @@
+// src/express/index.js
+import { renderHTML } from '../rendering/html-renderer.js';
+export function expressEngine() {
+    return (filePath, options, callback) => {
+        try {
+            // options contains the Coherent object structure
+            const html = renderHTML(options);
+            callback(null, html);
+        }
+        catch (error) {
+            callback(error);
+        }
+    };
+}
+// Helper for Express apps
+export function setupCoherent(app) {
+    app.engine('coherent', expressEngine());
+    app.set('view engine', 'coherent');
+}
+//# sourceMappingURL=index.js.map

package/dist/express/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/express/index.js"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D,MAAM,UAAU,aAAa;IACzB,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;QACnC,IAAI,CAAC;YACD,iDAAiD;YACjD,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;YACjC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,QAAQ,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACL,CAAC,CAAC;AACN,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,aAAa,CAAC,GAAG;IAC7B,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,EAAE,CAAC,CAAC;IACxC,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;AACvC,CAAC"}