npm - pulse-js-framework - Versions diffs - 1.9.0 → 1.9.2 - Mend

pulse-js-framework 1.9.0 → 1.9.2

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

package/cli/build.js +38 -0
package/cli/index.js +12 -1
package/cli/ssg.js +490 -0
package/compiler/parser.js +20 -0
package/compiler/transformer/view.js +80 -1
package/package.json +17 -1
package/runtime/ssr-mismatch.js +388 -0
package/runtime/ssr-preload.js +228 -0
package/runtime/ssr-serializer.js +3 -1
package/runtime/ssr-stream.js +388 -0
package/runtime/ssr.js +103 -3
package/server/express.js +108 -0
package/server/fastify.js +119 -0
package/server/hono.js +107 -0
package/server/index.js +208 -0
package/server/utils.js +254 -0

package/runtime/ssr.js CHANGED Viewed

@@ -2,6 +2,8 @@
  * Pulse SSR - Server-Side Rendering Module
  *
  * Provides server-side rendering and client-side hydration for Pulse applications.
+ * Includes streaming SSR, selective rendering (@client/@server), and hydration
+ * mismatch detection.
  *
  * @module pulse-js-framework/runtime/ssr
  *
@@ -25,6 +27,15 @@
  * hydrate('#app', () => App(), {
  *   state: window.__PULSE_STATE__
  * });
+ *
+ * @example
+ * // Streaming SSR
+ * import { renderToStream } from 'pulse-js-framework/runtime/ssr';
+ *
+ * const stream = renderToStream(() => App(), {
+ *   shellStart: '<!DOCTYPE html><html><body><div id="app">',
+ *   shellEnd: '</div></body></html>'
+ * });
  */
 import { createContext, batch, setSSRMode as setPulseSSRMode, isSSRMode } from './pulse.js';
@@ -298,6 +309,76 @@ export function hydrate(target, componentFactory, options = {}) {
   };
 }
+// ============================================================================
+// Selective SSR: ClientOnly / ServerOnly (#39)
+// ============================================================================
+/**
+ * Render content only on the client side. During SSR, renders the fallback
+ * (or an empty comment node). On the client, renders the main content.
+ *
+ * Use this for browser-only components (charts, maps, animations, etc.)
+ * that would break during server-side rendering.
+ *
+ * @param {Function} clientFactory - Factory function for client-side content
+ * @param {Function} [fallbackFactory] - Optional fallback factory for SSR
+ * @returns {*} DOM node(s) or comment placeholder
+ *
+ * @example
+ * import { ClientOnly } from 'pulse-js-framework/runtime/ssr';
+ *
+ * const chart = ClientOnly(
+ *   () => el('canvas.chart', { onmount: initChart }),
+ *   () => el('.placeholder', 'Chart loading...')
+ * );
+ *
+ * @example
+ * // In .pulse file with @client directive:
+ * // .chart @client { canvas "Loading..." }
+ */
+export function ClientOnly(clientFactory, fallbackFactory) {
+  if (isSSR()) {
+    // During SSR: render fallback or empty placeholder
+    if (fallbackFactory) {
+      return fallbackFactory();
+    }
+    // Return a comment node as placeholder
+    const adapter = getAdapter();
+    return adapter.createComment('client-only');
+  }
+  // On client: render the actual content
+  return clientFactory();
+}
+/**
+ * Render content only during SSR. On the client, renders an empty comment node.
+ *
+ * Use this for server-only content like JSON-LD structured data,
+ * meta tags, or server-side analytics scripts.
+ *
+ * @param {Function} serverFactory - Factory function for server-side content
+ * @returns {*} DOM node(s) or comment placeholder
+ *
+ * @example
+ * import { ServerOnly } from 'pulse-js-framework/runtime/ssr';
+ *
+ * const seoData = ServerOnly(
+ *   () => el('script[type=application/ld+json]', JSON.stringify(schema))
+ * );
+ *
+ * @example
+ * // In .pulse file with @server directive:
+ * // .seo @server { script[type=application/ld+json] "{seoJson}" }
+ */
+export function ServerOnly(serverFactory) {
+  if (isSSR()) {
+    return serverFactory();
+  }
+  // On client: empty placeholder
+  const adapter = getAdapter();
+  return adapter.createComment('server-only');
+}
 // ============================================================================
 // State Serialization
 // ============================================================================
@@ -365,9 +446,12 @@ export function serializeState(state) {
   const preprocessed = preprocessForSerialization(state);
   return JSON.stringify(preprocessed)
-    // Escape </script> to prevent XSS
-    .replace(/<\/script/gi, '<\\/script')
-    .replace(/<!--/g, '<\\!--');
+    // Escape all < and > to prevent HTML parser interference in <script> context
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    // Escape unicode line/paragraph separators (invalid in JS strings pre-ES2019)
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
 }
 /**
@@ -455,6 +539,15 @@ export function clearSSRState() {
 export { isHydratingMode, getHydrationContext } from './ssr-hydrator.js';
 export { getSSRAsyncContext } from './ssr-async.js';
+// Streaming SSR (#38)
+export { renderToStream, renderToReadableStream } from './ssr-stream.js';
+// Hydration mismatch detection (#44)
+export { MismatchType, diffNodes, logMismatches, getSuggestion } from './ssr-mismatch.js';
+// Preload hints (#42)
+export { generatePreloadHints, getRoutePreloads, parseBuildManifest, createPreloadMiddleware, hintsToHTML } from './ssr-preload.js';
 // ============================================================================
 // Default Export
 // ============================================================================
@@ -465,6 +558,13 @@ export default {
   renderToStringSync,
   hydrate,
+  // Streaming
+  // renderToStream and renderToReadableStream are re-exported above
+  // Selective rendering
+  ClientOnly,
+  ServerOnly,
   // State management
   serializeState,
   deserializeState,

package/server/express.js ADDED Viewed

@@ -0,0 +1,108 @@
+/**
+ * Pulse Express Adapter
+ *
+ * Middleware for Express.js that handles SSR, static asset serving,
+ * and state serialization for Pulse applications.
+ *
+ * @module pulse-js-framework/server/express
+ *
+ * @example
+ * import express from 'express';
+ * import { createExpressMiddleware } from 'pulse-js-framework/server/express';
+ * import App from './src/App.js';
+ *
+ * const app = express();
+ *
+ * app.use(createExpressMiddleware({
+ *   app: ({ route }) => App({ route }),
+ *   templatePath: './dist/index.html',
+ *   distDir: './dist'
+ * }));
+ *
+ * app.listen(3000);
+ */
+import { join } from 'path';
+import { createPulseHandler, resolveStaticAsset } from './index.js';
+import { createRequestContext } from './utils.js';
+// ============================================================================
+// Express Middleware
+// ============================================================================
+/**
+ * @typedef {import('./index.js').PulseMiddlewareOptions} PulseMiddlewareOptions
+ */
+/**
+ * Create Express middleware for Pulse SSR.
+ *
+ * @param {PulseMiddlewareOptions} options - Middleware options
+ * @returns {Function} Express middleware (req, res, next)
+ *
+ * @example
+ * app.use(createExpressMiddleware({
+ *   app: ({ route }) => App({ route }),
+ *   templatePath: './dist/index.html',
+ *   distDir: './dist',
+ *   streaming: false
+ * }));
+ */
+export function createExpressMiddleware(options = {}) {
+  const { distDir = 'dist', serveStatic = true } = options;
+  const handler = createPulseHandler(options);
+  const resolvedDistDir = join(process.cwd(), distDir);
+  return async function pulseMiddleware(req, res, next) {
+    // Skip non-GET requests
+    if (req.method !== 'GET') {
+      return next();
+    }
+    const pathname = req.path || req.url;
+    // Serve static assets first
+    if (serveStatic && pathname.startsWith('/assets/')) {
+      const asset = resolveStaticAsset(pathname, resolvedDistDir);
+      if (asset) {
+        for (const [key, value] of Object.entries(asset.headers)) {
+          res.setHeader(key, value);
+        }
+        return res.status(asset.status).end(asset.content);
+      }
+    }
+    // Skip API routes
+    if (pathname.startsWith('/api/')) {
+      return next();
+    }
+    try {
+      const ctx = createRequestContext(req, 'express');
+      const result = await handler(ctx);
+      res.status(result.status);
+      for (const [key, value] of Object.entries(result.headers)) {
+        res.setHeader(key, value);
+      }
+      // Handle streaming response
+      if (result.stream) {
+        const { Readable } = await import('stream');
+        const nodeStream = Readable.fromWeb(result.stream);
+        nodeStream.pipe(res);
+        return;
+      }
+      res.end(result.body);
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export default { createExpressMiddleware };

package/server/fastify.js ADDED Viewed

@@ -0,0 +1,119 @@
+/**
+ * Pulse Fastify Adapter
+ *
+ * Plugin for Fastify that handles SSR, static asset serving,
+ * and state serialization for Pulse applications.
+ *
+ * @module pulse-js-framework/server/fastify
+ *
+ * @example
+ * import Fastify from 'fastify';
+ * import { createFastifyPlugin } from 'pulse-js-framework/server/fastify';
+ * import App from './src/App.js';
+ *
+ * const app = Fastify();
+ *
+ * app.register(createFastifyPlugin({
+ *   app: ({ route }) => App({ route }),
+ *   templatePath: './dist/index.html',
+ *   distDir: './dist'
+ * }));
+ *
+ * app.listen({ port: 3000 });
+ */
+import { join } from 'path';
+import { createPulseHandler, resolveStaticAsset } from './index.js';
+import { createRequestContext } from './utils.js';
+// ============================================================================
+// Fastify Plugin
+// ============================================================================
+/**
+ * @typedef {import('./index.js').PulseMiddlewareOptions} PulseMiddlewareOptions
+ */
+/**
+ * Create a Fastify plugin for Pulse SSR.
+ *
+ * @param {PulseMiddlewareOptions} options - Plugin options
+ * @returns {Function} Fastify plugin (fastify, opts, done)
+ *
+ * @example
+ * app.register(createFastifyPlugin({
+ *   app: ({ route }) => App({ route }),
+ *   templatePath: './dist/index.html',
+ *   distDir: './dist',
+ *   streaming: false
+ * }));
+ */
+export function createFastifyPlugin(options = {}) {
+  const { distDir = 'dist', serveStatic = true } = options;
+  const handler = createPulseHandler(options);
+  const resolvedDistDir = join(process.cwd(), distDir);
+  return async function pulsePlugin(fastify, opts) {
+    // Serve static assets
+    if (serveStatic) {
+      fastify.get('/assets/*', async (request, reply) => {
+        const pathname = request.url;
+        const asset = resolveStaticAsset(pathname, resolvedDistDir);
+        if (asset) {
+          for (const [key, value] of Object.entries(asset.headers)) {
+            reply.header(key, value);
+          }
+          return reply.status(asset.status).send(asset.content);
+        }
+        reply.callNotFound();
+      });
+    }
+    // Catch-all route for SSR (skip /api/* routes)
+    fastify.get('*', async (request, reply) => {
+      const pathname = new URL(request.url, 'http://localhost').pathname;
+      // Skip API routes
+      if (pathname.startsWith('/api/')) {
+        return reply.callNotFound();
+      }
+      // Skip asset requests that weren't found
+      if (pathname.startsWith('/assets/')) {
+        return reply.callNotFound();
+      }
+      try {
+        const ctx = createRequestContext(request, 'fastify');
+        const result = await handler(ctx);
+        reply.status(result.status);
+        for (const [key, value] of Object.entries(result.headers)) {
+          reply.header(key, value);
+        }
+        // Handle streaming response
+        if (result.stream) {
+          const { Readable } = await import('stream');
+          const nodeStream = Readable.fromWeb(result.stream);
+          return reply.send(nodeStream);
+        }
+        return reply.send(result.body);
+      } catch (error) {
+        fastify.log.error(error, '[Pulse/Fastify] SSR Error');
+        reply.status(500).send(
+          '<!DOCTYPE html><html><body><h1>Internal Server Error</h1></body></html>'
+        );
+      }
+    });
+  };
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export default { createFastifyPlugin };

package/server/hono.js ADDED Viewed

@@ -0,0 +1,107 @@
+/**
+ * Pulse Hono Adapter
+ *
+ * Middleware for Hono framework that handles SSR, static asset serving,
+ * and state serialization for Pulse applications.
+ *
+ * @module pulse-js-framework/server/hono
+ *
+ * @example
+ * import { Hono } from 'hono';
+ * import { createHonoMiddleware } from 'pulse-js-framework/server/hono';
+ * import App from './src/App.js';
+ *
+ * const app = new Hono();
+ *
+ * app.use('*', createHonoMiddleware({
+ *   app: ({ route }) => App({ route }),
+ *   templatePath: './dist/index.html',
+ *   distDir: './dist'
+ * }));
+ *
+ * export default app;
+ */
+import { join } from 'path';
+import { createPulseHandler, resolveStaticAsset } from './index.js';
+import { createRequestContext } from './utils.js';
+// ============================================================================
+// Hono Middleware
+// ============================================================================
+/**
+ * @typedef {import('./index.js').PulseMiddlewareOptions} PulseMiddlewareOptions
+ */
+/**
+ * Create Hono middleware for Pulse SSR.
+ *
+ * @param {PulseMiddlewareOptions} options - Middleware options
+ * @returns {Function} Hono middleware (c, next)
+ *
+ * @example
+ * app.use('*', createHonoMiddleware({
+ *   app: ({ route }) => App({ route }),
+ *   templatePath: './dist/index.html',
+ *   streaming: true  // Hono supports streaming natively
+ * }));
+ */
+export function createHonoMiddleware(options = {}) {
+  const { distDir = 'dist', serveStatic = true } = options;
+  const handler = createPulseHandler(options);
+  const resolvedDistDir = join(process.cwd(), distDir);
+  return async function pulseMiddleware(c, next) {
+    // Skip non-GET requests
+    if (c.req.method !== 'GET') {
+      return next();
+    }
+    const url = new URL(c.req.url);
+    const pathname = url.pathname;
+    // Serve static assets first
+    if (serveStatic && pathname.startsWith('/assets/')) {
+      const asset = resolveStaticAsset(pathname, resolvedDistDir);
+      if (asset) {
+        return new Response(asset.content, {
+          status: asset.status,
+          headers: asset.headers
+        });
+      }
+    }
+    // Skip API routes
+    if (pathname.startsWith('/api/')) {
+      return next();
+    }
+    try {
+      const ctx = createRequestContext(c.req.raw, 'hono');
+      const result = await handler(ctx);
+      // Handle streaming response (Hono supports Web Streams natively)
+      if (result.stream) {
+        return new Response(result.stream, {
+          status: result.status,
+          headers: result.headers
+        });
+      }
+      return c.html(result.body, result.status);
+    } catch (error) {
+      console.error('[Pulse/Hono] SSR Error:', error.message);
+      return c.html(
+        '<!DOCTYPE html><html><body><h1>Internal Server Error</h1></body></html>',
+        500
+      );
+    }
+  };
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export default { createHonoMiddleware };

package/server/index.js ADDED Viewed

@@ -0,0 +1,208 @@
+/**
+ * Pulse Server Framework Adapters
+ *
+ * Provides middleware factories for popular Node.js server frameworks.
+ * Handles SSR, static asset serving, and state serialization.
+ *
+ * @module pulse-js-framework/server
+ *
+ * @example
+ * // Express
+ * import express from 'express';
+ * import { createExpressMiddleware } from 'pulse-js-framework/server/express';
+ *
+ * const app = express();
+ * app.use(createExpressMiddleware({ app: () => App() }));
+ *
+ * @example
+ * // Hono
+ * import { Hono } from 'hono';
+ * import { createHonoMiddleware } from 'pulse-js-framework/server/hono';
+ *
+ * const app = new Hono();
+ * app.use('*', createHonoMiddleware({ app: () => App() }));
+ *
+ * @example
+ * // Fastify
+ * import Fastify from 'fastify';
+ * import { createFastifyPlugin } from 'pulse-js-framework/server/fastify';
+ *
+ * const app = Fastify();
+ * app.register(createFastifyPlugin({ app: () => App() }));
+ */
+import {
+  injectIntoTemplate,
+  readTemplate,
+  clearTemplateCache,
+  resolveStaticAsset,
+  createRequestContext,
+  getMimeType
+} from './utils.js';
+// ============================================================================
+// Common Middleware Factory
+// ============================================================================
+/**
+ * @typedef {Object} PulseMiddlewareOptions
+ * @property {Function} app - Component factory: (ctx) => App()
+ * @property {string} [template] - HTML template string
+ * @property {string} [templatePath] - Path to HTML template file
+ * @property {string} [distDir='dist'] - Distribution directory for static assets
+ * @property {boolean} [streaming=false] - Enable streaming SSR
+ * @property {number} [timeout=5000] - SSR timeout (ms)
+ * @property {Function} [onError] - Error handler: (error, ctx) => void
+ * @property {Function} [getPreloadHints] - Preload hint generator
+ * @property {boolean} [serveStatic=true] - Serve static assets from distDir
+ */
+/**
+ * Create a generic Pulse SSR handler.
+ * This is the core logic shared by all framework adapters.
+ *
+ * @param {PulseMiddlewareOptions} options - Middleware options
+ * @returns {Function} Handler: (requestContext) => Promise<{status, headers, body}>
+ */
+export function createPulseHandler(options = {}) {
+  const {
+    app: appFactory,
+    template: templateStr,
+    templatePath,
+    distDir = 'dist',
+    streaming = false,
+    timeout = 5000,
+    onError,
+    getPreloadHints
+  } = options;
+  if (!appFactory) {
+    throw new Error('[Pulse Server] "app" option is required: provide a component factory function.');
+  }
+  return async function handleRequest(requestContext) {
+    try {
+      // Get template
+      const template = templateStr || (templatePath ? readTemplate(templatePath) : getDefaultTemplate());
+      // Generate preload hints if available
+      const head = getPreloadHints ? getPreloadHints(requestContext.pathname) : '';
+      if (streaming) {
+        return await handleStreamingSSR(appFactory, template, requestContext, { timeout, head });
+      }
+      return await handleStringSSR(appFactory, template, requestContext, { timeout, head });
+    } catch (error) {
+      if (onError) {
+        onError(error, requestContext);
+      }
+      return {
+        status: 500,
+        headers: { 'Content-Type': 'text/html; charset=utf-8' },
+        body: '<!DOCTYPE html><html><body><h1>Internal Server Error</h1></body></html>'
+      };
+    }
+  };
+}
+/**
+ * Handle string-based SSR (full page render).
+ * @private
+ */
+async function handleStringSSR(appFactory, template, ctx, options = {}) {
+  const { renderToString, serializeState } = await import('../runtime/ssr.js');
+  const { html, state } = await renderToString(
+    () => appFactory({ route: ctx.pathname, query: ctx.query }),
+    { waitForAsync: true, timeout: options.timeout, serializeState: true }
+  );
+  const stateScript = state
+    ? `<script>window.__PULSE_STATE__=${serializeState(state)};</script>`
+    : '';
+  const page = injectIntoTemplate(template, {
+    html,
+    state: stateScript,
+    head: options.head || ''
+  });
+  return {
+    status: 200,
+    headers: { 'Content-Type': 'text/html; charset=utf-8' },
+    body: page
+  };
+}
+/**
+ * Handle streaming SSR.
+ * @private
+ */
+async function handleStreamingSSR(appFactory, template, ctx, options = {}) {
+  const { renderToStream } = await import('../runtime/ssr-stream.js');
+  // Split template at app placeholder
+  const [shellStart, shellEnd] = template.split('<!--app-html-->');
+  const headContent = options.head || '';
+  const shellStartWithHead = headContent
+    ? shellStart.replace('</head>', `${headContent}\n</head>`)
+    : shellStart;
+  const stream = renderToStream(
+    () => appFactory({ route: ctx.pathname, query: ctx.query }),
+    {
+      shellStart: shellStartWithHead,
+      shellEnd: shellEnd || '',
+      timeout: options.timeout
+    }
+  );
+  return {
+    status: 200,
+    headers: { 'Content-Type': 'text/html; charset=utf-8', 'Transfer-Encoding': 'chunked' },
+    stream
+  };
+}
+/**
+ * Get default HTML template.
+ * @returns {string}
+ */
+function getDefaultTemplate() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Pulse App</title>
+</head>
+<body>
+  <div id="app"><!--app-html--></div>
+  <!--app-state-->
+  <script type="module" src="/assets/main.js"></script>
+</body>
+</html>`;
+}
+// ============================================================================
+// Re-exports
+// ============================================================================
+export { injectIntoTemplate, readTemplate, clearTemplateCache, resolveStaticAsset, createRequestContext, getMimeType };
+// ============================================================================
+// Default Export
+// ============================================================================
+export default {
+  createPulseHandler,
+  injectIntoTemplate,
+  readTemplate,
+  clearTemplateCache,
+  resolveStaticAsset,
+  createRequestContext,
+  getMimeType
+};