@gravito/signal 3.1.0 → 4.0.0

package/src/index.ts

@@ -1,41 +0,0 @@
-/**
- * OrbitSignal - The central Event Bus and Mail Service for Gravito.
- *
- * This module provides the core infrastructure for sending emails and managing
- * cross-module signals within the Gravito ecosystem. It supports multiple
- * transport drivers, template rendering, and a robust development environment.
- *
- * @packageDocumentation
- */
-
-// import './augmentation'
-
-export type { Queueable } from '@gravito/stream'
-export { DevMailbox, type MailboxEntry } from './dev/DevMailbox'
-export { MailErrorCode, MailTransportError } from './errors'
-export type { MailEvent, MailEventHandler, MailEventType } from './events'
-export { Mailable } from './Mailable'
-export { OrbitSignal } from './OrbitSignal'
-export { HtmlRenderer } from './renderers/HtmlRenderer'
-export { MjmlRenderer } from './renderers/MjmlRenderer'
-export * from './renderers/mjml-templates'
-export { ReactMjmlRenderer } from './renderers/ReactMjmlRenderer'
-export type { Renderer, RenderResult } from './renderers/Renderer'
-export { TemplateRenderer } from './renderers/TemplateRenderer'
-export { VueMjmlRenderer } from './renderers/VueMjmlRenderer'
-export { TypedMailable } from './TypedMailable'
-export { BaseTransport, type TransportOptions } from './transports/BaseTransport'
-export { LogTransport } from './transports/LogTransport'
-export { MemoryTransport } from './transports/MemoryTransport'
-export { SesTransport } from './transports/SesTransport'
-export { SmtpTransport } from './transports/SmtpTransport'
-export type { Transport } from './transports/Transport'
-export type {
-  Address,
-  Attachment,
-  Envelope,
-  MailConfig,
-  Message,
-} from './types'
-export { type SendGridWebhookConfig, SendGridWebhookDriver } from './webhooks/SendGridWebhookDriver'
-export { SesWebhookDriver } from './webhooks/SesWebhookDriver'

package/src/renderers/HtmlRenderer.ts

@@ -1,41 +0,0 @@
-import { stripHtml } from '../utils/html'
-import type { Renderer, RenderResult } from './Renderer'
-
-/**
- * Renderer for plain HTML content.
- *
- * The simplest renderer - accepts raw HTML strings and automatically generates
- * a plain text version by stripping HTML tags. Ideal for pre-rendered HTML or
- * when using external HTML generation libraries.
- *
- * @example
- * ```typescript
- * const renderer = new HtmlRenderer('<h1>Hello</h1>');
- * const result = await renderer.render();
- * // result.html: '<h1>Hello</h1>'
- * // result.text: 'Hello'
- * ```
- *
- * @public
- * @since 3.0.0
- */
-export class HtmlRenderer implements Renderer {
-  /**
-   * Creates an instance of HtmlRenderer.
-   *
-   * @param content - The raw HTML string to be rendered.
-   */
-  constructor(private content: string) {}
-
-  /**
-   * Returns the original HTML and a stripped plain text version.
-   *
-   * @returns A promise resolving to the rendered content.
-   */
-  async render(): Promise<RenderResult> {
-    return {
-      html: this.content,
-      text: stripHtml(this.content),
-    }
-  }
-}

package/src/renderers/MjmlRenderer.ts

@@ -1,73 +0,0 @@
-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

@@ -1,94 +0,0 @@
-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,66 +0,0 @@
-import { stripHtml } from '../utils/html'
-import type { Renderer, RenderResult } from './Renderer'
-
-/**
- * Renderer for React component-based emails.
- *
- * 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
- * const renderer = new ReactRenderer(MyComponent, { title: 'Welcome' });
- * const result = await renderer.render({ name: 'John' });
- * ```
- *
- * @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,
-    private deps: {
-      createElement?: (...args: any[]) => any
-      renderToStaticMarkup?: (element: any) => string
-    } = {}
-  ) {}
-
-  /**
-   * 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
-    const renderToStaticMarkup =
-      this.deps.renderToStaticMarkup ?? (await import('react-dom/server')).renderToStaticMarkup
-
-    const mergedProps = { ...this.props, ...data } as P
-
-    const element = createElement(this.component, mergedProps)
-    const html = renderToStaticMarkup(element)
-
-    const fullHtml = html.startsWith('<!DOCTYPE') ? html : `<!DOCTYPE html>${html}`
-
-    return {
-      html: fullHtml,
-      text: stripHtml(html),
-    }
-  }
-}

package/src/renderers/Renderer.ts

@@ -1,67 +0,0 @@
-/**
- * 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 {
-  /**
-   * The rendered HTML string.
-   *
-   * This is the primary content used for the email body.
-   */
-  html: 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.
- *
- * 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
- */
-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,84 +0,0 @@
-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.
- * 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 result = await renderer.render({ name: 'John' });
- * ```
- *
- * @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 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: stripHtml(html),
-    }
-  }
-
-  /**
-   * 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

@@ -1,99 +0,0 @@
-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,71 +0,0 @@
-import { stripHtml } from '../utils/html'
-import type { Renderer, RenderResult } from './Renderer'
-
-/**
- * Renderer for Vue component-based emails.
- *
- * 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
- * const renderer = new VueRenderer(MyComponent, { title: 'Welcome' });
- * const result = await renderer.render({ name: 'John' });
- * ```
- *
- * @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,
-    private deps: {
-      createSSRApp?: (...args: any[]) => any
-      h?: (...args: any[]) => any
-      renderToString?: (app: any) => Promise<string>
-    } = {}
-  ) {}
-
-  /**
-   * 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
-    const h = this.deps.h ?? (await import('vue')).h
-    const renderToString =
-      this.deps.renderToString ?? (await import('@vue/server-renderer')).renderToString
-
-    const mergedProps = { ...this.props, ...data }
-
-    const app = createSSRApp({
-      render: () => h(this.component, mergedProps),
-    })
-
-    const html = await renderToString(app)
-
-    const fullHtml = html.startsWith('<!DOCTYPE') ? html : `<!DOCTYPE html>${html}`
-
-    return {
-      html: fullHtml,
-      text: stripHtml(html),
-    }
-  }
-}

package/src/renderers/mjml-templates.ts

@@ -1,50 +0,0 @@
-/**
- * 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>
-`