@tstdl/base 0.93.36 → 0.93.38

package/source/sse/server-sent-events.ts

@@ -1,126 +0,0 @@
-import { NotSupportedError } from '#/errors/not-supported.error.js';
-import { ReplaySubject, distinctUntilChanged, filter, fromEvent, map, merge, share, shareReplay, startWith, takeUntil, type Observable } from 'rxjs';
-
-/**
- * Represents the possible states of a Server-Sent Events connection.
- */
-export enum ServerSentEventsState {
-
-  /**
-   * The connection is currently being established.
-   */
-  Connecting = 0,
-
-  /**
-   * The connection is open and ready to receive events.
-   */
-  Open = 1,
-
-  /**
-   * The connection is closed.
-   */
-  Closed = 2,
-}
-
-/**
- * A wrapper around the EventSource API, providing an RxJS-friendly interface for Server-Sent Events.
- */
-export class ServerSentEvents {
-  private readonly eventSource: EventSource;
-  private readonly closeSubject: ReplaySubject<void>;
-
-  /**
-   * An observable that emits when the connection is open.
-   */
-  readonly open$: Observable<void>;
-
-  /**
-   * An observable that emits when the connection is closed.
-   */
-  readonly close$: Observable<void>;
-
-  /**
-   * An observable that emits when an error occurs with the connection.
-   */
-  readonly error$: Observable<Event>;
-
-  /**
-   * An observable that emits the current state of the connection.
-   */
-  readonly state$: Observable<ServerSentEventsState>;
-
-  /**
-   * An observable that emits `true` when the connection is in the 'Connecting' state, `false` otherwise.
-   */
-  readonly isConnecting$: Observable<boolean>;
-
-  /**
-   * An observable that emits `true` when the connection is in the 'Open' state, `false` otherwise.
-   */
-  readonly isOpen$: Observable<boolean>;
-
-  /**
-   * An observable that emits `true` when the connection is in the 'Closed' state, `false` otherwise.
-   */
-  readonly isClosed$: Observable<boolean>;
-
-  /**
-   * Gets the current state of the Server-Sent Events connection.
-   * @returns The current state.
-   * @throws If the readyState of the EventSource is unknown.
-   */
-  get state(): ServerSentEventsState {
-    switch (this.eventSource.readyState) {
-      case EventSource.CONNECTING:
-        return ServerSentEventsState.Connecting;
-
-      case EventSource.OPEN:
-        return ServerSentEventsState.Open;
-
-      case EventSource.CLOSED:
-        return ServerSentEventsState.Closed;
-
-      default:
-        throw new NotSupportedError(`Unknown EventSource readyState ${this.eventSource.readyState}`);
-    }
-  }
-
-  /**
-   * Creates a new ServerSentEvents instance.
-   * @param url The URL of the server-sent events endpoint.
-   * @param options Optional EventSource initialization options.
-   */
-  constructor(url: string, options?: EventSourceInit) {
-    this.eventSource = new EventSource(url, options);
-    this.closeSubject = new ReplaySubject(1);
-
-    const open$ = fromEvent(this.eventSource, 'open');
-    this.close$ = this.closeSubject.asObservable();
-    this.error$ = fromEvent(this.eventSource, 'error').pipe(takeUntil(this.close$), share());
-
-    this.state$ = merge(open$, this.error$, this.close$).pipe(startWith(undefined), map(() => this.state), distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
-    this.isConnecting$ = this.state$.pipe(map((state) => state == ServerSentEventsState.Connecting), shareReplay({ bufferSize: 1, refCount: true }));
-    this.isOpen$ = this.state$.pipe(map((state) => state == ServerSentEventsState.Open), shareReplay({ bufferSize: 1, refCount: true }));
-    this.isClosed$ = this.state$.pipe(map((state) => state == ServerSentEventsState.Closed), shareReplay({ bufferSize: 1, refCount: true }));
-
-    this.open$ = this.isOpen$.pipe(filter((open) => open), map(() => undefined), takeUntil(this.close$), share());
-  }
-
-  /**
-   * Returns an observable of message events for a specific event type or default to 'message' event.
-   * @param event The event type to listen for. Defaults to 'message'.
-   * @returns An observable of message events.
-   */
-  message$(event?: string): Observable<MessageEvent<string>> {
-    return fromEvent<MessageEvent<string>>(this.eventSource, event ?? 'message').pipe(takeUntil(this.close$));
-  }
-
-  /**
-   * Closes the Server-Sent Events connection.
-   */
-  close(): void {
-    this.eventSource.close();
-    this.closeSubject.next();
-    this.closeSubject.complete();
-  }
-}

package/source/supports.ts

@@ -1,7 +0,0 @@
-export const supportsReadableStream = (typeof ReadableStream == 'function');
-export const supportsBlob = (typeof Blob == 'function');
-export const supportsBuffer = (typeof Buffer == 'function');
-export const supportsStructuredClone = (typeof structuredClone == 'function');
-export const supportsNotification = (typeof Notification == 'function');
-export const supportsColoredStdout = (typeof process == 'object' && (process.stdout.hasColors?.() ?? false));
-export const supportsColoredStderr = (typeof process == 'object' && (process.stderr.hasColors?.() ?? false));

package/source/templates/README.md

@@ -1,261 +0,0 @@
-# @tstdl/templates
-
-A powerful and extensible templating engine for TypeScript applications.
-
-This module provides a robust system for defining, resolving, and rendering templates from various sources and in multiple formats, including strings, JSX, Handlebars, and MJML for responsive emails.
-
-## Table of Contents
-
-- [Features](#features)
-- [Core Concepts](#core-concepts)
-  - [Rendering Flow](#rendering-flow)
-- [Usage](#usage)
-  - [1. Setup](#1-setup)
-  - [2. Simple In-Memory String Template](#2-simple-in-memory-string-template)
-  - [3. File-based Handlebars Template](#3-file-based-handlebars-template)
-  - [4. JSX/MJML Email Template](#4-jsxmjml-email-template)
-- [API Summary](#api-summary)
-
-## Features
-
-- **Extensible Architecture:** Easily add custom template sources (Providers), content resolvers (Resolvers), and templating engines (Renderers).
-- **Multiple Formats:** Built-in support for simple strings, JSX components, Handlebars, and MJML.
-- **Flexible Template Sources:** Load templates programmatically from memory (`MemoryTemplateProvider`) or from the file system (`FileTemplateProvider`).
-- **Type-Safe by Design:** Leverages TypeScript for creating well-defined, type-safe templates and contexts.
-- **Dependency Injection:** Seamlessly integrates with the `@tstdl/injector` for configuration and extensibility.
-
-## Core Concepts
-
-The module is built around a few key components that work together to provide its flexibility.
-
-- **`TemplateService`**: The main entry point for rendering templates. It orchestrates the other components to produce the final output.
-- **`Template`**: A model that defines a template. It consists of a `name` and a collection of `fields` (e.g., `subject`, `body`). Each field specifies how its content should be retrieved and processed.
-- **`TemplateProvider`**: Responsible for *loading* `Template` definitions. For example, `MemoryTemplateProvider` holds templates defined in code, while `FileTemplateProvider` loads them from `.ts` or `.js` files.
-- **`TemplateResolver`**: Resolves a template field into its raw, un-rendered content. For example, `FileTemplateResolver` reads a file's content from a path specified in a field, while `StringTemplateResolver` simply returns a string or executes a function defined in a field.
-- **`TemplateRenderer`**: Takes the raw content from a resolver and renders it using a specific engine and a data context. Examples include `StringTemplateRenderer`, `JsxTemplateRenderer`, `HandlebarsTemplateRenderer`, and `MjmlTemplateRenderer`.
-
-### Rendering Flow
-
-When you call `templateService.render('my-template', { user: ... })`:
-
-1.  The `TemplateProvider` is used to load the `Template` definition for `'my-template'`.
-2.  For each `field` within the template:
-    a. The `TemplateResolverProvider` finds the appropriate `TemplateResolver` based on the field's `resolver` property (e.g., `'file'`).
-    b. The `TemplateResolver` processes the field to get the raw template content (e.g., reads a `.hbs` file from disk).
-    c. The `TemplateRendererProvider` finds the appropriate `TemplateRenderer` based on the field's `renderer` property (e.g., `'handlebars'`).
-    d. The `TemplateRenderer` takes the raw content and the context data (e.g., `{ user: ... }`) to produce the final rendered string.
-3.  The service returns an object containing the rendered content for each field.
-
-## Usage
-
-### 1. Setup
-
-First, configure the module in your application's bootstrap file. You need to register at least one provider, resolver, and renderer.
-
-```typescript
-import { configureTemplates } from '@tstdl/templates';
-import { MemoryTemplateProvider } from '@tstdl/templates/providers';
-import { StringTemplateRenderer } from '@tstdl/templates/renderers';
-import { StringTemplateResolver } from '@tstdl/templates/resolvers';
-
-// In your application's bootstrap file
-configureTemplates({
-  templateProvider: MemoryTemplateProvider,
-  templateResolvers: [StringTemplateResolver],
-  templateRenderers: [StringTemplateRenderer],
-});
-```
-
-### 2. Simple In-Memory String Template
-
-This example defines a template programmatically, stores it in memory, and renders it using a simple string function.
-
-```typescript
-import { inject } from '@tstdl/injector';
-import { TemplateService, simpleTemplate } from '@tstdl/templates';
-import { MemoryTemplateProvider } from '@tstdl/templates/providers';
-import { stringTemplateField } from '@tstdl/templates/resolvers';
-
-// 1. Define the template and its data context
-type WelcomeTemplateContext = { user: { name: string } };
-
-const welcomeTemplate = simpleTemplate<WelcomeTemplateContext>(
-  'welcome-message',
-  stringTemplateField({
-    renderer: 'string',
-    template: (context) => `Hello, ${context.user.name}!`
-  })
-);
-
-// 2. Add the template to the provider
-const memoryProvider = inject(MemoryTemplateProvider);
-memoryProvider.add(welcomeTemplate.name, welcomeTemplate);
-
-// 3. Render it using the service
-const templateService = inject(TemplateService);
-const result = await templateService.render(welcomeTemplate, { user: { name: 'Alice' } });
-
-console.log(result.fields.template); // Output: "Hello, Alice!"
-```
-
-### 3. File-based Handlebars Template
-
-This example demonstrates loading a template definition and its content from the file system and rendering it with Handlebars.
-
-**a. Configuration**
-
-```typescript
-import { configureTemplates } from '@tstdl/templates';
-import { configureFileTemplateProvider, FileTemplateProvider } from '@tstdl/templates/providers';
-import { HandlebarsTemplateRenderer } from '@tstdl/templates/renderers';
-import { configureFileTemplateResolver, FileTemplateResolver } from '@tstdl/templates/resolvers';
-
-// Configure base paths for loading template definitions and their content files
-configureFileTemplateProvider({ basePath: './src/templates/definitions' });
-configureFileTemplateResolver({ basePath: './src/templates/content' });
-
-configureTemplates({
-  templateProvider: FileTemplateProvider,
-  templateResolvers: [FileTemplateResolver],
-  templateRenderers: [HandlebarsTemplateRenderer],
-});
-```
-
-**b. Template Definition (`./src/templates/definitions/product-alert.ts`)**
-
-```typescript
-import { Template } from '@tstdl/templates';
-import { fileTemplateField } from '@tstdl/templates/resolvers';
-
-export type ProductAlertContext = { product: { name: string }, user: { name: string } };
-
-const template: Template<{ subject: true, body: true }, any, ProductAlertContext> = {
-  name: 'product-alert',
-  fields: {
-    subject: fileTemplateField({
-      renderer: 'handlebars',
-      templateFile: 'product-alert/subject.hbs'
-    }),
-    body: fileTemplateField({
-      renderer: 'handlebars',
-      templateFile: 'product-alert/body.hbs'
-    })
-  }
-};
-
-export default template;
-```
-
-**c. Template Content**
-
-- `./src/templates/content/product-alert/subject.hbs`:
-  ```handlebars
-  {{product.name}} is back in stock!
-  ```
-- `./src/templates/content/product-alert/body.hbs`:
-  ```handlebars
-  Hi {{user.name}}, the product {{product.name}} you were interested in is now available.
-  ```
-
-**d. Rendering**
-
-```typescript
-import { inject } from '@tstdl/injector';
-import { TemplateService } from '@tstdl/templates';
-
-const templateService = inject(TemplateService);
-const result = await templateService.render('product-alert', {
-  user: { name: 'Bob' },
-  product: { name: 'Super Widget' }
-});
-
-console.log(result.fields.subject); // "Super Widget is back in stock!"
-console.log(result.fields.body);    // "Hi Bob, the product Super Widget you were interested in is now available."
-```
-
-### 4. JSX/MJML Email Template
-
-Create responsive HTML emails using JSX and MJML. The `MjmlTemplateRenderer` can use another renderer, like JSX, as a preprocessor.
-
-**a. Configuration**
-
-```typescript
-import { configureTemplates } from '@tstdl/templates';
-import { MemoryTemplateProvider } from '@tstdl/templates/providers';
-import { JsxTemplateRenderer, MjmlTemplateRenderer } from '@tstdl/templates/renderers';
-import { JsxTemplateResolver } from '@tstdl/templates/resolvers';
-
-configureTemplates({
-  templateProvider: MemoryTemplateProvider,
-  templateResolvers: [JsxTemplateResolver],
-  templateRenderers: [JsxTemplateRenderer, MjmlTemplateRenderer],
-});
-```
-
-**b. Template Definition and Rendering**
-
-```typescript
-import { inject } from '@tstdl/injector';
-import { TemplateService } from '@tstdl/templates';
-import { MemoryTemplateProvider } from '@tstdl/templates/providers';
-import { simpleJsxTemplate } from '@tstdl/templates/resolvers';
-
-// 1. Define the data context and the JSX component
-type OrderConfirmationContext = { order: { id: string } };
-
-const OrderConfirmationEmail = ({ order }: OrderConfirmationContext) => (
-  <mjml>
-    <mj-body>
-      <mj-section>
-        <mj-column>
-          <mj-text>Your order #{order.id} has been confirmed!</mj-text>
-        </mj-column>
-      </mj-section>
-    </mj-body>
-  </mjml>
-);
-
-// 2. Create a simple template definition using the JSX component
-const emailTemplate = simpleJsxTemplate<OrderConfirmationContext>(
-  'order-confirmation-email',
-  OrderConfirmationEmail
-);
-
-// 3. Set the renderer to 'mjml-jsx' to preprocess JSX before rendering MJML
-emailTemplate.fields.template.renderer = 'mjml-jsx';
-
-// 4. Add to provider and render
-const memoryProvider = inject(MemoryTemplateProvider);
-memoryProvider.add(emailTemplate.name, emailTemplate);
-
-const templateService = inject(TemplateService);
-const result = await templateService.render('order-confirmation-email', { order: { id: '123-ABC' } });
-
-// result.fields.template now contains responsive HTML
-console.log(result.fields.template);
-```
-
-## API Summary
-
-| Class/Function | Arguments | Return Type | Description |
-| :--- | :--- | :--- | :--- |
-| `configureTemplates(config)` | `config: Partial<TemplateModuleConfig>` | `void` | Configures the template module with providers, resolvers, and renderers. |
-| `TemplateService` | | | The main service for rendering templates. |
-| `  .render(keyOrTemplate, context)` | `keyOrTemplate: string \| Template`, `context?: Record` | `Promise<TemplateServiceRenderResult>` | Renders a template by key or definition with the given context. |
-| `  .get(key)` | `key: string` | `Promise<Template>` | Retrieves a template definition by its key. |
-| `TemplateProvider` (abstract) | | | Base class for template providers. |
-| `  .get(key)` | `key: string` | `Promise<Template>` | Loads a template definition. |
-| `MemoryTemplateProvider` | | | A provider that stores templates in memory. |
-| `  .add(key, template)` | `key: string`, `template: Template` | `void` | Adds a template to the provider. |
-| `FileTemplateProvider` | | | A provider that loads template definitions from JavaScript/TypeScript files. |
-| `TemplateResolver` (abstract) | | | Base class for template resolvers. |
-| `  .resolve(field)` | `field: TemplateField` | `Promise<unknown>` | Resolves a template field to its raw content. |
-| `FileTemplateResolver` | | | Resolves a `templateFile` path into the file's string content. |
-| `JsxTemplateResolver` | | | Resolves a `template` property containing a JSX component. |
-| `StringTemplateResolver` | | | Resolves a `template` property containing a string or a function returning a string. |
-| `TemplateRenderer` (abstract) | | | Base class for template renderers. |
-| `  .render(renderObject, context)` | `renderObject: TemplateRenderObject`, `context?: Record` | `Promise<string>` | Renders the raw template content with a context. |
-| `HandlebarsTemplateRenderer`| | | Renders templates using Handlebars.js. |
-| `JsxTemplateRenderer` | | | Renders JSX templates to an HTML string. |
-| `MjmlTemplateRenderer` | | | Renders MJML to responsive HTML. Can use another renderer (e.g., JSX) as a preprocessor. |
-| `StringTemplateRenderer` | | | Renders string templates by simple replacement or function execution. |

package/source/templates/index.ts

@@ -1,9 +0,0 @@
-export * from './module.js';
-export * from './template-renderer.provider.js';
-export * from './template-resolver.provider.js';
-export * from './template.model.js';
-export * from './template.provider.js';
-export * from './template.renderer.js';
-export * from './template.resolver.js';
-export * from './template.service.js';
-export * from './tokens.js';

package/source/templates/module.ts

@@ -1,41 +0,0 @@
-import { Injector } from '#/injector/injector.js';
-import type { Type } from '#/types/index.js';
-import { isDefined } from '#/utils/type-guards.js';
-import { StringTemplateRenderer } from './renderers/string.template-renderer.js';
-import { StringTemplateResolver } from './resolvers/string.template-resolver.js';
-import { TemplateProvider } from './template.provider.js';
-import { TemplateRenderer } from './template.renderer.js';
-import { TemplateResolver } from './template.resolver.js';
-import { TEMPLATE_RENDERERS, TEMPLATE_RESOLVERS } from './tokens.js';
-
-export type TemplateModuleConfig = {
-  templateProvider: Type<TemplateProvider> | undefined,
-  templateResolvers: Type<TemplateResolver>[],
-  templateRenderers: Type<TemplateRenderer>[],
-};
-
-export const templateModuleConfig: TemplateModuleConfig = {
-  templateProvider: undefined,
-  templateResolvers: [StringTemplateResolver],
-  templateRenderers: [StringTemplateRenderer],
-};
-
-Injector.registerSingleton(TEMPLATE_RESOLVERS, { useToken: TemplateResolver, resolveAll: true });
-Injector.registerSingleton(TEMPLATE_RENDERERS, { useToken: TemplateRenderer, resolveAll: true });
-
-/**
- * configure mail module
- */
-export function configureTemplates(config: Partial<TemplateModuleConfig> = {}): void {
-  if (isDefined(config.templateProvider)) {
-    Injector.registerSingleton(TemplateProvider, { useToken: config.templateProvider });
-  }
-
-  if (isDefined(config.templateResolvers)) {
-    Injector.register(TemplateResolver, config.templateResolvers.map((resolver) => ({ useToken: resolver })));
-  }
-
-  if (isDefined(config.templateRenderers)) {
-    Injector.register(TemplateRenderer, config.templateRenderers.map((renderer) => ({ useToken: renderer })));
-  }
-}

package/source/templates/providers/file.template-provider.ts

@@ -1,53 +0,0 @@
-import * as path from 'node:path';
-
-import { BadRequestError } from '#/errors/bad-request.error.js';
-import { InjectArg, Singleton } from '#/injector/decorators.js';
-import type { Resolvable, resolveArgumentType } from '#/injector/interfaces.js';
-import { Schema } from '#/schema/index.js';
-import { Template } from '../template.model.js';
-import { TemplateProvider } from '../template.provider.js';
-
-export type FileTemplateProviderConfig = {
-  basePath?: string
-};
-
-export type FileTemplateProviderArgument = string;
-
-export const fileTemplateProviderConfig: FileTemplateProviderConfig = {};
-
-const keyPattern = /^[\w\-/]+$/u;
-
-@Singleton({
-  defaultArgumentProvider: () => fileTemplateProviderConfig.basePath
-})
-export class FileTemplateProvider extends TemplateProvider implements Resolvable<FileTemplateProviderArgument> {
-  private readonly basePath: string;
-
-  declare readonly [resolveArgumentType]: FileTemplateProviderArgument;
-  constructor(@InjectArg() basePath: string) {
-    super();
-
-    this.basePath = path.resolve(basePath);
-  }
-
-  async get<T extends Template = Template>(key: string): Promise<T> {
-    if (!keyPattern.test(key)) {
-      throw new BadRequestError('Illegal template key. Only a-z, A-Z, 0-9, _ and - are allowed.');
-    }
-
-    const filePath = path.resolve(this.basePath, `${key}.js`);
-
-    if (!filePath.startsWith(this.basePath)) {
-      throw new BadRequestError(`Illegal file path. Must be inside "${this.basePath}".`);
-    }
-
-    const templateModule = await import(filePath) as { template?: unknown, default?: unknown };
-    const fileContent = templateModule.template ?? templateModule.default;
-
-    return Schema.parse(Template, fileContent) as T;
-  }
-}
-
-export function configureFileTemplateProvider(config: Partial<FileTemplateProviderConfig> = {}): void {
-  fileTemplateProviderConfig.basePath = config.basePath ?? fileTemplateProviderConfig.basePath;
-}

package/source/templates/providers/index.ts

@@ -1,2 +0,0 @@
-export * from './file.template-provider.js'
-export * from './memory.template-provider.js'

package/source/templates/providers/memory.template-provider.ts

@@ -1,29 +0,0 @@
-import { Singleton } from '#/injector/decorators.js';
-import { isUndefined } from '#/utils/type-guards.js';
-import type { Template } from '../template.model.js';
-import { TemplateProvider } from '../template.provider.js';
-
-@Singleton()
-export class MemoryTemplateProvider extends TemplateProvider {
-  private readonly map: Map<string, Template>;
-
-  constructor() {
-    super();
-
-    this.map = new Map();
-  }
-
-  add(key: string, template: Template): void {
-    this.map.set(key, template);
-  }
-
-  get(key: string): Template {
-    const template = this.map.get(key);
-
-    if (isUndefined(template)) {
-      throw new Error(`Template ${key} not available.`);
-    }
-
-    return template;
-  }
-}