@tstdl/base 0.93.139 → 0.93.140

package/templates/README.md

@@ -0,0 +1,287 @@
+# @tstdl/base/templates
+
+A powerful, extensible, and type-safe templating engine for TypeScript applications. It provides a unified interface for defining, resolving, and rendering templates from various sources (memory, file system) using multiple engines (Handlebars, JSX, MJML).
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Setup](#setup)
+  - [In-Memory String Template](#in-memory-string-template)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [File-Based Handlebars Templates](#file-based-handlebars-templates)
+  - [Responsive Emails with MJML & JSX](#responsive-emails-with-mjml--jsx)
+  - [Template Preprocessing](#template-preprocessing)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Modular Architecture**: Decouples template storage (Providers), content retrieval (Resolvers), and rendering logic (Renderers).
+- **Multi-Engine Support**: Built-in support for:
+  - **Strings**: Simple text replacement or function execution.
+  - **Handlebars**: Logic-less templates with helpers and partials.
+  - **JSX**: Type-safe component-based rendering (via Preact).
+  - **MJML**: Responsive email framework.
+- **Flexible Sources**: Load templates from the file system or define them programmatically in memory.
+- **Type Safety**: Leverages TypeScript generics to ensure template contexts and options are strictly typed.
+- **Dependency Injection**: Fully integrated with `@tstdl/base/injector` for easy configuration and extension.
+
+## Core Concepts
+
+The module relies on four main components working in harmony:
+
+1.  **Template**: A data model defining the structure of a template. It contains a `name` and a set of `fields` (e.g., `subject`, `body`). Each field specifies a `resolver` (how to get the content) and a `renderer` (how to process it).
+2.  **TemplateProvider**: Responsible for locating and loading the `Template` definition object.
+    - `MemoryTemplateProvider`: Stores templates in a Map.
+    - `FileTemplateProvider`: Loads template definitions from `.js` files.
+3.  **TemplateResolver**: Fetches the raw content for a specific field.
+    - `StringTemplateResolver`: Returns a string or executes a function.
+    - `FileTemplateResolver`: Reads content from a file on disk.
+    - `JsxTemplateResolver`: Returns a JSX component.
+4.  **TemplateRenderer**: Transforms the raw content and a data context into the final output string.
+    - `HandlebarsTemplateRenderer`, `JsxTemplateRenderer`, `MjmlTemplateRenderer`, etc.
+
+## 🚀 Basic Usage
+
+### Setup
+
+To use the module, you must configure it during your application's bootstrap phase. This registers the necessary providers and renderers with the dependency injection system.
+
+```typescript
+import { configureTemplates } from '@tstdl/base/templates';
+import { MemoryTemplateProvider } from '@tstdl/base/templates/providers';
+import { StringTemplateRenderer } from '@tstdl/base/templates/renderers';
+import { StringTemplateResolver } from '@tstdl/base/templates/resolvers';
+
+// In your bootstrap.ts or app.ts
+configureTemplates({
+  templateProvider: MemoryTemplateProvider,
+  templateResolvers: [StringTemplateResolver],
+  templateRenderers: [StringTemplateRenderer],
+});
+```
+
+### In-Memory String Template
+
+This example defines a template in code and renders it using a simple string function.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { TemplateService, simpleTemplate } from '@tstdl/base/templates';
+import { MemoryTemplateProvider } from '@tstdl/base/templates/providers';
+import { stringTemplateField } from '@tstdl/base/templates/resolvers';
+
+// 1. Define the context type for type safety
+type WelcomeContext = { user: string };
+
+// 2. Create the template definition
+const welcomeTemplate = simpleTemplate<WelcomeContext>(
+  'welcome',
+  stringTemplateField({
+    renderer: 'string',
+    template: (context) => `Hello, ${context.user}!`,
+  }),
+);
+
+async function main() {
+  // 3. Register the template with the provider
+  const provider = inject(MemoryTemplateProvider);
+  provider.add('welcome', welcomeTemplate);
+
+  // 4. Render the template
+  const service = inject(TemplateService);
+  const result = await service.render('welcome', { user: 'Alice' });
+
+  console.log(result.fields.template); // Output: "Hello, Alice!"
+}
+```
+
+## 🔧 Advanced Topics
+
+### File-Based Handlebars Templates
+
+For larger applications, it is common to store template definitions and content in files.
+
+**1. Configuration**
+
+```typescript
+import { resolve } from 'node:path';
+import { configureTemplates } from '@tstdl/base/templates';
+import { configureFileTemplateProvider, FileTemplateProvider } from '@tstdl/base/templates/providers';
+import { HandlebarsTemplateRenderer } from '@tstdl/base/templates/renderers';
+import { configureFileTemplateResolver, FileTemplateResolver } from '@tstdl/base/templates/resolvers';
+
+const templatesDir = resolve(process.cwd(), 'templates');
+
+configureTemplates({
+  templateProvider: FileTemplateProvider,
+  templateResolvers: [FileTemplateResolver],
+  templateRenderers: [HandlebarsTemplateRenderer],
+});
+
+// Set base paths for definitions and content files
+configureFileTemplateProvider({ basePath: resolve(templatesDir, 'definitions') });
+configureFileTemplateResolver({ basePath: resolve(templatesDir, 'content') });
+```
+
+**2. Template Definition (`templates/definitions/invoice.ts`)**
+
+```typescript
+import { Template } from '@tstdl/base/templates';
+import { fileTemplateField } from '@tstdl/base/templates/resolvers';
+
+export type InvoiceContext = { id: string; total: number };
+
+// Define a template with two fields: subject and html body
+const template: Template<{ subject: true; html: true }, any, InvoiceContext> = {
+  name: 'invoice',
+  fields: {
+    subject: fileTemplateField({
+      renderer: 'handlebars',
+      templateFile: 'invoice/subject.hbs', // Relative to resolver basePath
+    }),
+    html: fileTemplateField({
+      renderer: 'handlebars',
+      templateFile: 'invoice/body.hbs',
+    }),
+  },
+};
+
+export default template;
+```
+
+**3. Content Files**
+
+- `templates/content/invoice/subject.hbs`: `Invoice #{{id}}`
+- `templates/content/invoice/body.hbs`: `<h1>Invoice #{{id}}</h1><p>Total: {{total}}</p>`
+
+**4. Rendering**
+
+```typescript
+const service = inject(TemplateService);
+const result = await service.render('invoice', { id: '1001', total: 59.99 });
+
+console.log(result.fields.subject); // "Invoice #1001"
+console.log(result.fields.html); // "<h1>Invoice #1001</h1><p>Total: 59.99</p>"
+```
+
+### Responsive Emails with MJML & JSX
+
+You can combine the power of JSX components with MJML to create type-safe, responsive emails.
+
+**1. Configuration**
+
+```typescript
+import { configureTemplates } from '@tstdl/base/templates';
+import { MemoryTemplateProvider } from '@tstdl/base/templates/providers';
+import { JsxTemplateRenderer, MjmlTemplateRenderer } from '@tstdl/base/templates/renderers';
+import { JsxTemplateResolver } from '@tstdl/base/templates/resolvers';
+
+configureTemplates({
+  templateProvider: MemoryTemplateProvider,
+  templateResolvers: [JsxTemplateResolver],
+  templateRenderers: [JsxTemplateRenderer, MjmlTemplateRenderer],
+});
+```
+
+**2. Component & Template**
+
+```tsx
+import { inject } from '@tstdl/base/injector';
+import { TemplateService } from '@tstdl/base/templates';
+import { MemoryTemplateProvider } from '@tstdl/base/templates/providers';
+import { simpleJsxTemplate } from '@tstdl/base/templates/resolvers';
+
+type AlertContext = { message: string };
+
+// Define the email layout using JSX and MJML tags
+const AlertEmail = ({ message }: AlertContext) => (
+  <mjml>
+    <mj-body>
+      <mj-section>
+        <mj-column>
+          <mj-text color="#F45E43">{message}</mj-text>
+        </mj-column>
+      </mj-section>
+    </mj-body>
+  </mjml>
+);
+
+// Create the template definition
+const alertTemplate = simpleJsxTemplate('alert', AlertEmail);
+
+// IMPORTANT: Tell the renderer to use 'mjml-jsx'.
+// This means: Use 'jsx' renderer first, then pass the result to 'mjml' renderer.
+alertTemplate.fields.template.renderer = 'mjml-jsx';
+
+// Register and render
+const provider = inject(MemoryTemplateProvider);
+provider.add('alert', alertTemplate);
+
+const service = inject(TemplateService);
+const result = await service.render('alert', { message: 'System Down!' });
+
+// result.fields.template contains the compiled HTML from MJML
+```
+
+### Template Preprocessing
+
+The `MjmlTemplateRenderer` supports a special renderer string format: `mjml-[preprocessor]`.
+
+If you specify `renderer: 'mjml-handlebars'`, the system will:
+
+1.  Resolve the content (e.g., from a file).
+2.  Render it using the `HandlebarsTemplateRenderer`.
+3.  Pass the resulting string (which should be valid MJML) to the `MjmlTemplateRenderer`.
+4.  Output the final HTML.
+
+This allows you to use Handlebars or JSX logic to generate your MJML structure dynamically.
+
+## 📚 API
+
+### Configuration & Service
+
+| Export                       | Description                                                       |
+| :--------------------------- | :---------------------------------------------------------------- |
+| `configureTemplates(config)` | Configures the module with providers, resolvers, and renderers.   |
+| `TemplateService`            | The main service. Use `.render(key, context)` to generate output. |
+| `TemplateProvider`           | Abstract base class for template sources.                         |
+| `TemplateResolver`           | Abstract base class for content retrieval.                        |
+| `TemplateRenderer`           | Abstract base class for content rendering.                        |
+
+### Providers
+
+| Class                                   | Description                                                            |
+| :-------------------------------------- | :--------------------------------------------------------------------- |
+| `MemoryTemplateProvider`                | Stores template definitions in an in-memory Map.                       |
+| `FileTemplateProvider`                  | Loads template definitions from `.js` files in a configured directory. |
+| `configureFileTemplateProvider(config)` | Sets the base path for `FileTemplateProvider`.                         |
+
+### Resolvers
+
+| Class                                   | Description                                                            |
+| :-------------------------------------- | :--------------------------------------------------------------------- |
+| `StringTemplateResolver`                | Resolves content from a string or function in the template definition. |
+| `FileTemplateResolver`                  | Reads content from a file path specified in the template definition.   |
+| `JsxTemplateResolver`                   | Resolves content from a JSX component in the template definition.      |
+| `configureFileTemplateResolver(config)` | Sets the base path for `FileTemplateResolver`.                         |
+
+### Renderers
+
+| Class                        | Description                                                              |
+| :--------------------------- | :----------------------------------------------------------------------- |
+| `StringTemplateRenderer`     | Renders simple strings or executes string-returning functions.           |
+| `HandlebarsTemplateRenderer` | Renders Handlebars templates. Supports helpers and partials.             |
+| `JsxTemplateRenderer`        | Renders JSX components to strings (via `preact-render-to-string`).       |
+| `MjmlTemplateRenderer`       | Renders MJML strings to HTML. Supports preprocessing (e.g., `mjml-jsx`). |
+
+### Helpers
+
+| Function                             | Description                                                         |
+| :----------------------------------- | :------------------------------------------------------------------ |
+| `simpleTemplate(name, field)`        | Creates a `Template` object with a single field named `template`.   |
+| `simpleJsxTemplate(name, component)` | Creates a `Template` object for a JSX component.                    |
+| `fileTemplateField(options)`         | Helper to create a field definition using `FileTemplateResolver`.   |
+| `stringTemplateField(options)`       | Helper to create a field definition using `StringTemplateResolver`. |
+| `jsxTemplateField(options)`          | Helper to create a field definition using `JsxTemplateResolver`.    |

package/testing/README.md

@@ -0,0 +1,157 @@
+# Testing in tstdl
+
+This project uses **[Vitest](https://vitest.dev/)** as its primary testing framework. It is configured to handle both unit and integration tests with support for dependency injection and database-backed scenarios.
+
+## Quick Start
+
+### 1. Set up Infrastructure
+
+Some tests require external services like a database. These must be started if the tests depend on them.
+
+```bash
+cd base
+docker-compose up -d
+```
+
+### 2. Run Tests
+
+You can run all tests or filter by module/file.
+
+```bash
+# Run all tests
+npm test
+
+# Run a specific test file
+npx test source/injector/tests/basic.test.ts
+
+# Run a specific folder of tests
+npx test source/injector/tests/
+```
+
+### 3. Coverage
+
+To generate a code coverage report for a specific module:
+
+```bash
+npm test --coverage --coverage.include="source/injector/**/*.ts" source/injector/
+```
+
+### 4. Correctness
+
+Regularily use TypesScript's type checker to ensure correctness.
+
+```bash
+npx tsc --noEmit
+```
+
+## Project Structure
+
+- **Test Files**: Always located in a `<module>/tests/` subdirectory within their respective module.
+- **Naming**: Files must end in `.test.ts`.
+- **Infrastructure**: Shared testing utilities are located in `source/testing/`.
+
+## Writing Unit Tests
+
+Unit tests should be isolated and not require external services. Use Vitest's `describe`, `test`/`it`, and `expect`.
+
+```typescript
+import { describe, expect, test } from 'vitest';
+import { myFunc } from '../my-module.js';
+
+describe('MyModule', () => {
+  test('should do something', () => {
+    const result = myFunc();
+    expect(result).toBe(true);
+  });
+});
+```
+
+## Writing Integration Tests
+
+Integration tests verify the interaction between multiple components or with external services (Database, S3, etc.). Use the `setupIntegrationTest` helper to initialize the environment.
+
+### Setup Helper: `setupIntegrationTest`
+
+The `setupIntegrationTest` utility (found in `source/testing/integration-setup.ts`) automates:
+
+1.  **Injector**: Creates a new `TestInjector`.
+2.  **Logging**: Configures pretty-print logging with configurable levels.
+3.  **Database**: Sets up the ORM and provides a `Database` instance.
+4.  **Schema Isolation**: Automatically creates and uses PostgreSQL schemas for isolation.
+5.  **Modules**: Optional configuration for `taskQueue`, `authentication`, `objectStorage`, `notification`, etc.
+
+### Integration Test Example
+
+```typescript
+import { beforeAll, describe, expect, it } from 'vitest';
+import { setupIntegrationTest } from '#/testing/index.js';
+import { MyService } from '../my-service.js';
+
+describe('MyService Integration', () => {
+  let injector;
+
+  beforeAll(async () => {
+    // Setup with database and specific modules
+    ({ injector } = await setupIntegrationTest({
+      modules: { taskQueue: true },
+      orm: { schema: 'test_my_service' },
+    }));
+  });
+
+  it('should process data through the database', async () => {
+    const service = injector.resolve(MyService);
+    const result = await service.process();
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+## Best Practices & Guidelines
+
+### 1. Isolation
+
+- **Schemas**: Always use a unique PostgreSQL schema for your integration test suite via `orm: { schema: '...' }`.
+- **Resource Naming**: When testing shared infrastructure (Task Queues, S3 Buckets, Rate Limiters), append a random suffix or timestamp to the resource name (e.g., `const queueName = \`test-queue-${crypto.randomUUID()}\``).
+- **Cleanup**: Use `truncateTables` or `dropTables` in `beforeAll` or `beforeEach` to ensure a clean state.
+- **Tenant Data**: Use `clearTenantData` if your tests are multi-tenant and use random tenant IDs to avoid collisions when concurrently running tests.
+- **Schema**: Make sure you use the correct schema when clearing data with any of the helper functions. They must match the schema used by the module.
+
+### 2. Dependency Injection & Mocking
+
+- **Resolving**: Use `injector.resolve(Token)` or `injector.resolveAsync(Token)` to get instances.
+- **Mocking Services**: For services managed by the `Injector`, prefer registering a mock value over using `vi.mock`.
+  ```typescript
+  const mailServiceMock = { send: vi.fn() };
+  injector.register(MailService, { useValue: mailServiceMock });
+  ```
+- **Injection Context**: Any code that uses repositories or services relying on `inject()` outside of a class constructor/initializer **must** be wrapped in `runInInjectionContext(injector, async () => { ... })`.
+- **Mock Reset**: Always call `vi.clearAllMocks()` in `beforeEach` if using spys or mocks to ensure test independence.
+
+### 3. Integration Test Patterns
+
+- **Schema Management**:
+  - **Preferred**: Use the `modules` option in `setupIntegrationTest`. This automatically runs the necessary migrations for standard modules (e.g., `taskQueue`, `authentication`, `notification`).
+  - **Fallback**: Use Manual DDL via `database.execute(sql\`...\`)`**only** for test-specific entities (like local`@Table`classes defined inside your test file) that are not part of a standard module. Always call`dropTables` before creating them to ensure a fresh start.
+- **Background Workers**: When testing workers or loops, use a `CancellationToken` to stop them in `afterEach` or `afterAll`.
+- **Timeouts**: Use the `timeout(ms)` helper from `#/utils/timing.js` for tests involving refills, retries, or background processing. Prefer `vi.useFakeTimers()` only when real-time passage is too slow for the test suite.
+- **Logging**: Test should generally not output logs unless for active debugging. Use try-catch for expected errors and assert on the error message instead of relying on logs.
+
+### 4. Performance
+
+- Use `beforeAll` for heavy setup (like schema and table creation) and `beforeEach` for lightweight data resetting (truncation).
+- Prefer integration tests over unit tests when reasonably possible to cover more code paths and reduce the need for extensive mocking and stubbing.
+
+### 5. Coding Style
+
+- **Explicit Types**: Use explicit return types for methods and functions.
+- **Async/Await**: Always use `async/await` for asynchronous code to improve readability and error handling.
+- **Mocking Types**: When mocking, use `Partial<Type>` or `Pick<Type, 'method1' | 'method2'>` to maintain type safety, where type is the original type being mocked.
+- **Avoid `any`**: Strive to use specific types or `unknown` if required to maintain type safety.
+- **Descriptive Names**: Use descriptive names for test files, cases and variables to improve readability.
+
+### 6. Common Helpers (from `source/testing/`)
+
+- `setupIntegrationTest(options)`: Main entry point for integration tests.
+- `truncateTables(database, schema, tables)`: Clears data from specified tables.
+- `dropTables(database, schema, tables)`: Drops specified tables.
+- `clearTenantData(database, schema, tables, tenantId)`: Deletes data for a specific tenant.