@gravito/signal 3.0.3 → 3.0.4

package/src/renderers/MjmlRenderer.ts

@@ -0,0 +1,73 @@
+import { stripHtml } from '../utils/html'
+import type { Renderer, RenderResult } from './Renderer'
+
+/**
+ * Renderer for MJML-based emails.
+ *
+ * MJML is a markup language designed to reduce the pain of coding a responsive email.
+ * This renderer lazily loads the `mjml` package to keep the core lightweight.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new MjmlRenderer('<mjml><mj-body>...</mj-body></mjml>');
+ * const result = await renderer.render();
+ * ```
+ *
+ * @public
+ * @since 1.1.0
+ */
+export class MjmlRenderer implements Renderer {
+  /**
+   * Creates an instance of MjmlRenderer.
+   *
+   * @param content - The MJML markup string to be rendered.
+   * @param options - Optional MJML transformation options.
+   * @param deps - Optional dependency injection for testing.
+   */
+  constructor(
+    private content: string,
+    private options: Record<string, any> = {},
+    private deps: {
+      mjml2html?: (mjml: string, options?: any) => any
+    } = {}
+  ) {}
+
+  /**
+   * Renders the MJML content to static HTML.
+   *
+   * This method performs a dynamic import of `mjml` to ensure it's only
+   * loaded if this renderer is actually used.
+   *
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If MJML dependencies cannot be loaded or rendering fails.
+   */
+  async render(): Promise<RenderResult> {
+    let mjml2html = this.deps.mjml2html
+
+    if (!mjml2html) {
+      try {
+        mjml2html = (await import('mjml')).default
+      } catch (_e) {
+        throw new Error(
+          '[OrbitSignal] The "mjml" package is required for MjmlRenderer. Please install it using "bun add mjml".'
+        )
+      }
+    }
+
+    const { html, errors } = mjml2html(this.content, {
+      validationLevel: 'soft',
+      ...this.options,
+    })
+
+    if (errors && errors.length > 0 && this.options.validationLevel === 'strict') {
+      throw new Error(
+        `MJML rendering failed: ${errors.map((e: any) => e.formattedMessage).join(', ')}`
+      )
+    }
+
+    return {
+      html,
+      text: stripHtml(html),
+    }
+  }
+}

package/src/renderers/ReactMjmlRenderer.ts

@@ -0,0 +1,94 @@
+import { stripHtml } from '../utils/html'
+import type { Renderer, RenderResult } from './Renderer'
+
+/**
+ * Renderer for React component-based MJML emails.
+ *
+ * Renders React components to MJML string using SSR, then converts
+ * the MJML to responsive HTML.
+ *
+ * @typeParam P - Props type for the React component.
+ * @public
+ * @since 1.1.0
+ */
+export class ReactMjmlRenderer<P extends object = object> implements Renderer {
+  /**
+   * Creates an instance of ReactMjmlRenderer.
+   *
+   * @param component - The React component to render.
+   * @param props - Initial props for the component.
+   * @param options - Optional MJML transformation options.
+   * @param deps - Optional dependency injection for testing.
+   */
+  constructor(
+    private component: any,
+    private props?: P,
+    private options: Record<string, any> = {},
+    private deps: {
+      createElement?: (...args: any[]) => any
+      renderToStaticMarkup?: (element: any) => string
+      mjml2html?: (mjml: string, options?: any) => any
+    } = {}
+  ) {}
+
+  /**
+   * Renders the React component to a static HTML string via MJML.
+   *
+   * @param data - Runtime data to be merged with initial props.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If MJML rendering fails.
+   */
+  async render(data: Record<string, unknown>): Promise<RenderResult> {
+    let { createElement, renderToStaticMarkup, mjml2html } = this.deps
+
+    if (!createElement || !renderToStaticMarkup) {
+      try {
+        const react = await import('react')
+        const reactDomServer = await import('react-dom/server')
+        createElement ??= react.createElement
+        renderToStaticMarkup ??= reactDomServer.renderToStaticMarkup
+      } catch (_e) {
+        throw new Error(
+          '[OrbitSignal] The "react" and "react-dom" packages are required for ReactMjmlRenderer. Please install them using "bun add react react-dom".'
+        )
+      }
+    }
+
+    if (!mjml2html) {
+      try {
+        mjml2html = (await import('mjml')).default
+      } catch (_e) {
+        throw new Error(
+          '[OrbitSignal] The "mjml" package is required for ReactMjmlRenderer. Please install it using "bun add mjml".'
+        )
+      }
+    }
+
+    const mergedProps = { ...this.props, ...data } as P
+    const element = createElement?.(this.component, mergedProps)
+    const mjml = renderToStaticMarkup?.(element)
+    if (!mjml) {
+      throw new Error('Failed to render MJML template')
+    }
+
+    const result = mjml2html?.(mjml, {
+      validationLevel: 'soft',
+      ...this.options,
+    })
+    if (!result) {
+      throw new Error('Failed to convert MJML to HTML')
+    }
+    const { html, errors } = result
+
+    if (errors && errors.length > 0 && this.options.validationLevel === 'strict') {
+      throw new Error(
+        `MJML rendering failed: ${errors.map((e: any) => e.formattedMessage).join(', ')}`
+      )
+    }
+
+    return {
+      html,
+      text: stripHtml(html),
+    }
+  }
+}

package/src/renderers/ReactRenderer.ts

@@ -1,26 +1,31 @@
+import { stripHtml } from '../utils/html'
 import type { Renderer, RenderResult } from './Renderer'
 
 /**
  * Renderer for React component-based emails.
  *
- * Renders React components to static HTML for email delivery.
- * Supports server-side rendering with optional dependency injection
- * for testing.
+ * Renders React components to static HTML using server-side rendering (SSR).
+ * It lazily loads React and ReactDOM dependencies only when needed, preventing
+ * unnecessary bundle bloat for users who do not use React renderers.
  *
  * @example
  * ```typescript
- * import { WelcomeEmail } from './emails/WelcomeEmail'
- *
- * const renderer = new ReactRenderer(WelcomeEmail, { name: 'John' })
- * const { html, text } = await renderer.render({ date: new Date() })
+ * const renderer = new ReactRenderer(MyComponent, { title: 'Welcome' });
+ * const result = await renderer.render({ name: 'John' });
  * ```
  *
- * @typeParam P - Props type for the React component
- *
- * @since 3.0.0
+ * @typeParam P - Props type for the React component.
  * @public
+ * @since 3.0.0
  */
 export class ReactRenderer<P extends object = object> implements Renderer {
+  /**
+   * Creates an instance of ReactRenderer.
+   *
+   * @param component - The React component to render.
+   * @param props - Initial props for the component.
+   * @param deps - Optional dependency injection for testing.
+   */
   constructor(
     private component: any, // Use any to avoid hard React dependency in types
     private props?: P,
@@ -30,6 +35,16 @@ export class ReactRenderer<P extends object = object> implements Renderer {
     } = {}
   ) {}
 
+  /**
+   * Renders the React component to a static HTML string.
+   *
+   * This method performs dynamic imports of `react` and `react-dom/server`
+   * to ensure they are only loaded if this renderer is actually used.
+   *
+   * @param data - Runtime data to be merged with initial props.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If React dependencies cannot be loaded or rendering fails.
+   */
   async render(data: Record<string, unknown>): Promise<RenderResult> {
     // Dynamic imports to avoid hard dependencies on react/react-dom
     const createElement = this.deps.createElement ?? (await import('react')).createElement
@@ -45,17 +60,7 @@ export class ReactRenderer<P extends object = object> implements Renderer {
 
     return {
       html: fullHtml,
-      text: this.stripHtml(html),
+      text: stripHtml(html),
     }
   }
-
-  private stripHtml(html: string): string {
-    return html
-      .replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, '')
-      .replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, '')
-      .replace(/<[^>]+>/g, '')
-      .replace(/&nbsp;/g, ' ')
-      .replace(/\s+/g, ' ')
-      .trim()
-  }
 }

package/src/renderers/Renderer.ts

@@ -1,18 +1,53 @@
 /**
  * Result of a content rendering operation.
  *
+ * This interface defines the structure of the output produced by any renderer.
+ * It ensures consistency across different rendering strategies (HTML, React, Vue, etc.),
+ * providing both the final HTML for the email body and an optional plain text version
+ * for clients that do not support HTML.
+ *
+ * @example
+ * ```typescript
+ * const result: RenderResult = {
+ *   html: '<html><body><h1>Hello</h1></body></html>',
+ *   text: 'Hello'
+ * };
+ * ```
+ *
  * @public
  * @since 3.0.0
  */
 export interface RenderResult {
-  /** Rendered HTML string. */
+  /**
+   * The rendered HTML string.
+   *
+   * This is the primary content used for the email body.
+   */
   html: string
-  /** Optional rendered plain text string. */
+  /**
+   * Optional rendered plain text string.
+   *
+   * Used as a fallback for email clients that cannot display HTML or for accessibility.
+   */
   text?: string
 }
 
 /**
- * Interface for email content renderers (HTML, Template, React, Vue).
+ * Interface for email content renderers.
+ *
+ * Renderers are responsible for transforming various input formats (raw HTML,
+ * templates, or UI components) into a standardized {@link RenderResult}.
+ * This abstraction allows the mail system to support multiple view engines
+ * and frameworks interchangeably.
+ *
+ * @example
+ * ```typescript
+ * class MyRenderer implements Renderer {
+ *   async render(data: Record<string, unknown>): Promise<RenderResult> {
+ *     return { html: `<div>${data.name}</div>`, text: String(data.name) };
+ *   }
+ * }
+ * ```
  *
  * @public
  * @since 3.0.0
@@ -21,7 +56,12 @@ export interface Renderer {
   /**
    * Render the content into HTML and optionally plain text.
    *
+   * This method performs the actual transformation of the source content
+   * using the provided data context.
+   *
    * @param data - The data context for rendering.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If rendering fails due to syntax errors or missing dependencies.
    */
   render(data: Record<string, unknown>): Promise<RenderResult>
 }

package/src/renderers/TemplateRenderer.ts

@@ -1,51 +1,84 @@
+import { stripHtml } from '../utils/html'
 import type { Renderer, RenderResult } from './Renderer'
 
 /**
  * Renderer for template-based emails using Gravito Prism.
  *
- * Renders email templates from the filesystem using the Prism
- * template engine with support for data binding and layouts.
+ * Renders email templates from the filesystem using the Prism template engine.
+ * It uses a static cache for the template engine to avoid redundant initialization
+ * costs when rendering multiple emails from the same directory.
  *
  * @example
  * ```typescript
- * const renderer = new TemplateRenderer('welcome', './src/emails')
- * const { html, text } = await renderer.render({ name: 'John' })
+ * const renderer = new TemplateRenderer('welcome', './src/emails');
+ * const result = await renderer.render({ name: 'John' });
  * ```
  *
- * @since 3.0.0
  * @public
+ * @since 3.0.0
  */
 export class TemplateRenderer implements Renderer {
   private template: string
   private viewsDir: string
+  private static engineCache = new Map<string, any>()
 
+  /**
+   * Creates an instance of TemplateRenderer.
+   *
+   * @param templateName - The name of the template file (without extension).
+   * @param viewsDir - The directory containing template files. Defaults to `src/emails`.
+   */
   constructor(templateName: string, viewsDir?: string) {
     this.template = templateName
     // Default to src/emails if not provided, falling back to process cwd
     this.viewsDir = viewsDir || `${process.cwd()}/src/emails`
   }
 
+  /**
+   * Renders the template with the provided data.
+   *
+   * This method lazily loads `@gravito/prism` to ensure the core package
+   * remains lightweight for users who don't need template rendering.
+   *
+   * @param data - The data context for template interpolation.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If the template engine fails to load or rendering fails.
+   */
   async render(data: Record<string, unknown>): Promise<RenderResult> {
     // Dynamic import to avoid hard dependency on @gravito/prism
     const { TemplateEngine } = await import('@gravito/prism')
-    const engine = new TemplateEngine(this.viewsDir)
+
+    const cached = TemplateRenderer.engineCache.get(this.viewsDir)
+    const engine = cached || new TemplateEngine(this.viewsDir)
+
+    if (!cached) {
+      TemplateRenderer.engineCache.set(this.viewsDir, engine)
+    }
 
     // Disable automatic layout by default for emails, unless explicitly handled in template
     const html = engine.render(this.template, data, {})
 
     return {
       html,
-      text: this.stripHtml(html),
+      text: stripHtml(html),
     }
   }
 
-  private stripHtml(html: string): string {
-    return html
-      .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
-      .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
-      .replace(/<[^>]+>/g, '')
-      .replace(/&nbsp;/g, ' ')
-      .replace(/\s+/g, ' ')
-      .trim()
+  /**
+   * Clear template engine cache.
+   *
+   * Useful in development environments to force recompilation of templates
+   * after they have been modified on disk.
+   *
+   * @example
+   * ```typescript
+   * TemplateRenderer.clearCache();
+   * ```
+   *
+   * @public
+   * @since 3.1.0
+   */
+  static clearCache(): void {
+    TemplateRenderer.engineCache.clear()
   }
 }

package/src/renderers/VueMjmlRenderer.ts

@@ -0,0 +1,99 @@
+import { stripHtml } from '../utils/html'
+import type { Renderer, RenderResult } from './Renderer'
+
+/**
+ * Renderer for Vue component-based MJML emails.
+ *
+ * Renders Vue 3 components to MJML string using SSR, then converts
+ * the MJML to responsive HTML.
+ *
+ * @typeParam P - Props type for the Vue component.
+ * @public
+ * @since 1.1.0
+ */
+export class VueMjmlRenderer<P extends object = object> implements Renderer {
+  /**
+   * Creates an instance of VueMjmlRenderer.
+   *
+   * @param component - The Vue component to render.
+   * @param props - Initial props for the component.
+   * @param options - Optional MJML transformation options.
+   * @param deps - Optional dependency injection for testing.
+   */
+  constructor(
+    private component: any,
+    private props?: P,
+    private options: Record<string, any> = {},
+    private deps: {
+      createSSRApp?: (...args: any[]) => any
+      h?: (...args: any[]) => any
+      renderToString?: (app: any) => Promise<string>
+      mjml2html?: (mjml: string, options?: any) => any
+    } = {}
+  ) {}
+
+  /**
+   * Renders the Vue component to a static HTML string via MJML.
+   *
+   * @param data - Runtime data to be merged with initial props.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If MJML rendering fails.
+   */
+  async render(data: Record<string, unknown>): Promise<RenderResult> {
+    let { createSSRApp, h, renderToString, mjml2html } = this.deps
+
+    if (!createSSRApp || !h || !renderToString) {
+      try {
+        const vue = await import('vue')
+        const vueServerRenderer = await import('@vue/server-renderer')
+        createSSRApp ??= vue.createSSRApp
+        h ??= vue.h
+        renderToString ??= vueServerRenderer.renderToString
+      } catch (_e) {
+        throw new Error(
+          '[OrbitSignal] The "vue" and "@vue/server-renderer" packages are required for VueMjmlRenderer. Please install them using "bun add vue @vue/server-renderer".'
+        )
+      }
+    }
+
+    if (!mjml2html) {
+      try {
+        mjml2html = (await import('mjml')).default
+      } catch (_e) {
+        throw new Error(
+          '[OrbitSignal] The "mjml" package is required for VueMjmlRenderer. Please install it using "bun add mjml".'
+        )
+      }
+    }
+
+    const mergedProps = { ...this.props, ...data }
+    const app = createSSRApp?.({
+      render: () => h?.(this.component, mergedProps),
+    })
+
+    const mjml = await renderToString?.(app)
+    if (!mjml) {
+      throw new Error('Failed to render MJML template')
+    }
+
+    const result = mjml2html?.(mjml, {
+      validationLevel: 'soft',
+      ...this.options,
+    })
+    if (!result) {
+      throw new Error('Failed to convert MJML to HTML')
+    }
+    const { html, errors } = result
+
+    if (errors && errors.length > 0 && this.options.validationLevel === 'strict') {
+      throw new Error(
+        `MJML rendering failed: ${errors.map((e: any) => e.formattedMessage).join(', ')}`
+      )
+    }
+
+    return {
+      html,
+      text: stripHtml(html),
+    }
+  }
+}

package/src/renderers/VueRenderer.ts

@@ -1,26 +1,31 @@
+import { stripHtml } from '../utils/html'
 import type { Renderer, RenderResult } from './Renderer'
 
 /**
  * Renderer for Vue component-based emails.
  *
- * Renders Vue 3 components to static HTML for email delivery
- * using server-side rendering. Supports optional dependency
- * injection for testing.
+ * Renders Vue 3 components to static HTML using server-side rendering (SSR).
+ * It lazily loads Vue and `@vue/server-renderer` dependencies only when needed,
+ * preventing unnecessary bundle bloat for users who do not use Vue renderers.
  *
  * @example
  * ```typescript
- * import { WelcomeEmail } from './emails/WelcomeEmail.vue'
- *
- * const renderer = new VueRenderer(WelcomeEmail, { name: 'John' })
- * const { html, text } = await renderer.render({ date: new Date() })
+ * const renderer = new VueRenderer(MyComponent, { title: 'Welcome' });
+ * const result = await renderer.render({ name: 'John' });
  * ```
  *
- * @typeParam P - Props type for the Vue component
- *
- * @since 3.0.0
+ * @typeParam P - Props type for the Vue component.
  * @public
+ * @since 3.0.0
  */
 export class VueRenderer<P extends object = object> implements Renderer {
+  /**
+   * Creates an instance of VueRenderer.
+   *
+   * @param component - The Vue component to render.
+   * @param props - Initial props for the component.
+   * @param deps - Optional dependency injection for testing.
+   */
   constructor(
     private component: any, // Use any to avoid hard Vue dependency in types
     private props?: P,
@@ -31,6 +36,16 @@ export class VueRenderer<P extends object = object> implements Renderer {
     } = {}
   ) {}
 
+  /**
+   * Renders the Vue component to a static HTML string.
+   *
+   * This method performs dynamic imports of `vue` and `@vue/server-renderer`
+   * to ensure they are only loaded if this renderer is actually used.
+   *
+   * @param data - Runtime data to be merged with initial props.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If Vue dependencies cannot be loaded or rendering fails.
+   */
   async render(data: Record<string, unknown>): Promise<RenderResult> {
     // Dynamic imports to avoid hard dependencies on vue/@vue/server-renderer
     const createSSRApp = this.deps.createSSRApp ?? (await import('vue')).createSSRApp
@@ -50,17 +65,7 @@ export class VueRenderer<P extends object = object> implements Renderer {
 
     return {
       html: fullHtml,
-      text: this.stripHtml(html),
+      text: stripHtml(html),
     }
   }
-
-  private stripHtml(html: string): string {
-    return html
-      .replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, '')
-      .replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, '')
-      .replace(/<[^>]+>/g, '')
-      .replace(/&nbsp;/g, ' ')
-      .replace(/\s+/g, ' ')
-      .trim()
-  }
 }

package/src/renderers/mjml-templates.ts

@@ -0,0 +1,50 @@
+/**
+ * Base layout for MJML emails.
+ * Includes common head styles and responsive settings.
+ *
+ * Placeholder: {{content}}
+ */
+export const baseLayout = `
+<mjml>
+  <mj-head>
+    <mj-attributes>
+      <mj-all font-family="Arial, Helvetica, sans-serif" />
+      <mj-text font-size="16px" color="#333333" line-height="1.5" />
+      <mj-section padding="20px" />
+    </mj-attributes>
+    <mj-style>
+      .link-white { color: #ffffff !important; text-decoration: none; }
+      .footer-text { font-size: 12px; color: #999999; }
+    </mj-style>
+  </mj-head>
+  <mj-body background-color="#f4f4f4">
+    <mj-section background-color="#ffffff" padding-bottom="0px">
+      <mj-column>
+        <mj-image width="150px" src="https://gravito.dev/logo.png" alt="Gravito" />
+      </mj-column>
+    </mj-section>
+    
+    {{content}}
+
+    <mj-section>
+      <mj-column>
+        <mj-divider border-width="1px" border-color="#dddddd" />
+        <mj-text align="center" css-class="footer-text">
+          &copy; ${new Date().getFullYear()} Gravito Framework. All rights reserved.
+        </mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>
+`
+
+/**
+ * A simple transactional component layout.
+ */
+export const transactionLayout = `
+<mj-section background-color="#ffffff" padding-top="0px">
+  <mj-column>
+    {{content}}
+  </mj-column>
+</mj-section>
+`