@tstdl/base 0.93.139 → 0.93.141

package/README.md

@@ -0,0 +1,166 @@
+# @tstdl/base - A Comprehensive TypeScript Library
+
+**The Comprehensive TypeScript Standard Library for Modern Applications.**
+
+`@tstdl/base` is a robust, modular, and strictly type-safe foundation designed to accelerate the development of enterprise-grade applications. Whether you are building a server-side microservice, a complex web application, or a cross-platform tool, this library provides the architectural building blocks you need—from Dependency Injection and ORM to AI integration and reactive state management.
+
+## ✨ Key Philosophy
+
+- **Type Safety First:** Built entirely in TypeScript with rigorous type definitions, schemas, and generics to catch errors at compile time.
+- **Dependency Injection:** A powerful DI container (`@tstdl/base/injector`) sits at the core, allowing for testable, decoupled, and modular architectures.
+- **Code-First & Definition-First**: Define your data models and API contracts once in TypeScript and let the framework generate the necessary boilerplate and ensure consistency.
+- **Isomorphic Design:** Many modules work seamlessly across Node.js, Browsers, and Workers.
+- **Reactive & Async:** Built-in support for Signals, RxJS, and modern async patterns (Cancellation signals, Async iterables).
+- **Batteries Included:** Stop glueing together dozens of micro-packages. Get a cohesive set of tools that work together out of the box.
+
+## 📦 Installation
+
+```bash
+npm install @tstdl/base
+```
+
+## 🚀 Quick Start
+
+Most applications start by bootstrapping the Dependency Injection container and the Application lifecycle manager.
+
+```typescript
+import { Application, provideModule, provideSignalHandler } from '@tstdl/base/application';
+import { inject, Singleton } from '@tstdl/base/injector';
+import { Logger, provideConsoleLogTransport, PrettyPrintLogFormatter } from '@tstdl/base/logger';
+
+// 1. Define a Service
+@Singleton()
+class HelloWorldService {
+  private logger = inject(Logger, 'HelloWorld');
+
+  sayHello() {
+    this.logger.info('Hello from @tstdl/base!');
+  }
+}
+
+// 2. Define your Main Module
+async function main() {
+  const service = inject(HelloWorldService);
+  service.sayHello();
+}
+
+// 3. Run the Application
+Application.run('MyFirstApp', [
+  provideModule(main),
+  provideConsoleLogTransport(PrettyPrintLogFormatter), // Enable logging
+  provideSignalHandler(), // Handle Ctrl+C gracefully
+]);
+```
+
+## 🧩 Modules Overview
+
+### 🏗️ Architecture & Core
+
+Building blocks for application structure and lifecycle.
+
+- **`@tstdl/base/application`**: Bootstrapping, lifecycle management, and graceful shutdown.
+- **`@tstdl/base/injector`**: Powerful Dependency Injection container with scopes, tokens, and async resolution.
+- **`@tstdl/base/module`**: Standardized contracts for start/stop components and workers.
+- **`@tstdl/base/cancellation`**: RxJS-based cancellation tokens for managing async flows.
+- **`@tstdl/base/message-bus`**: Decoupled communication via local subjects or BroadcastChannel.
+- **`@tstdl/base/context`**: Type-safe execution context management (prop-drilling killer).
+
+### 🌐 API & Networking
+
+Robust tools for client-server communication.
+
+- **`@tstdl/base/api`**: Contract-first API definition sharing between client and server.
+- **`@tstdl/base/http`**: Isomorphic HTTP client/server abstraction with middleware support.
+- **`@tstdl/base/rpc`**: Type-safe Remote Procedure Calls for Workers and cross-window comms.
+- **`@tstdl/base/sse`**: Server-Sent Events with delta-compression support.
+
+### 💾 Data & Storage
+
+Persistence layers for databases, files, and caching.
+
+- **`@tstdl/base/orm`**: Code-first ORM for PostgreSQL (built on Drizzle) featuring repositories, transactions, **transparent column encryption** and **migrations**.
+- **`@tstdl/base/key-value-store`**: Abstract KV store with PostgreSQL implementation.
+- **`@tstdl/base/object-storage`**: S3-compatible storage abstraction with pre-signed URL support.
+- **`@tstdl/base/queue`**: Persistent background job queues with prioritization and batching.
+- **`@tstdl/base/lock`**: Distributed locking (Postgres) and local locking (Web Locks).
+- **`@tstdl/base/distributed-loop`**: Mechanism for running distributed loops synchronized across processes.
+- **`@tstdl/base/document-management`**: Full document lifecycle, classification, and workflow engine.
+
+### 🔒 Security & Auth
+
+Secure your application with ease.
+
+- **`@tstdl/base/authentication`**: Full-stack auth with JWTs, sessions, and impersonation.
+- **`@tstdl/base/openid-connect`**: OIDC client with PKCE and auto-discovery.
+- **`@tstdl/base/audit`**: Structured audit logging with contextual enrichment.
+- **`@tstdl/base/password`**: Strength estimation (zxcvbn) and breach detection (HIBP).
+
+### 🛠️ Utilities & Helpers
+
+Essential tools for everyday coding.
+
+- **`@tstdl/base/schema`**: Runtime validation and type inference.
+- **`@tstdl/base/utils`**: Extensive collection of async iterable helpers, crypto, JSONPath, and deep object manipulation.
+- **`@tstdl/base/serializer`**: JSON-compatible serialization handling circular refs and custom types.
+- **`@tstdl/base/data-structures`**: specialized data structures like circular buffers and weak ref maps.
+- **`@tstdl/base/error`**: Standardized serializable error classes (`NotFoundError`, `ForbiddenError`, etc.).
+- **`@tstdl/base/promise`**: Advanced promise implementations (`DeferredPromise`, `LazyPromise`, `CancelablePromise`).
+- **`@tstdl/base/disposable`**: Implementations of the `Disposable` and `AsyncDisposable` patterns.
+- **`@tstdl/base/logger`**: Structured logging with hierarchical contexts and pluggable transports.
+- **`@tstdl/base/types`**: Advanced TypeScript utility types (GeoJSON, Tagged types, DeepPartial).
+- **`@tstdl/base/enumerable`**: LINQ-inspired fluent API for collections and async streams.
+
+### 🤖 AI & Processing
+
+Modern capabilities for intelligent apps.
+
+- **`@tstdl/base/ai`**: Unified wrapper for Google Gemini and Vertex AI with structured output.
+- **`@tstdl/base/image`**: Abstraction for image processing services (e.g., Imgproxy).
+- **`@tstdl/base/process`**: Promise/Stream-based child process management.
+- **`@tstdl/base/threading`**: Thread pools for Node.js threads and Web Workers with RPC.
+- **`@tstdl/base/pool`**: Async object pooling for resource management.
+
+### 🖥️ UI & Rendering
+
+Tools for frontend logic and content generation.
+
+- **`@tstdl/base/signals`**: High-performance reactive state management based on Angular Signals.
+- **`@tstdl/base/dom`**: Reactive wrappers for DOM observers (Resize, Intersection) and file handling.
+- **`@tstdl/base/browser`**: Controller-based wrapper for Playwright automation.
+- **`@tstdl/base/pdf`**: Generate PDFs from HTML/Templates via headless browser.
+- **`@tstdl/base/mail`**: Email sending service with rich template support.
+- **`@tstdl/base/jsx`**: Lightweight SSR for JSX/TSX (Preact-based).
+- **`@tstdl/base/text`**: Reactive i18n/localization built on Signals.
+- **`@tstdl/base/templates`**: Multi-engine template rendering (Handlebars, JSX, MJML).
+- **`@tstdl/base/theme`**: Services for managing color palettes and CSS variables.
+- **`@tstdl/base/rxjs`**: A collection of RxJS operators.
+
+---
+
+## 🔧 Configuration
+
+Most server-side modules (`orm`, `mail`, `queue`, `ai`) require configuration during the application bootstrap phase.
+
+```typescript
+import { configureOrm } from '@tstdl/base/orm/server';
+import { configureAiService } from '@tstdl/base/ai';
+
+// Example bootstrap function
+export async function bootstrap() {
+  // Configure Database
+  configureOrm({
+    connection: {
+      /* Postgres config */
+    },
+  });
+
+  // Configure AI
+  configureAiService({
+    apiKey: process.env.GOOGLE_API_KEY,
+  });
+}
+```
+
+## 📖 Getting Started & Examples
+
+The best way to get started is to explore the **`examples/`** directory in the repository. It contains practical, runnable examples for many of the core modules, demonstrating how they work together to build a complete application.

package/ai/genkit/multi-region.plugin.js

@@ -39,7 +39,7 @@ export function vertexAiMultiLocation(options) {
                         ...request,
                         config: {
                             ...request.config,
-                            location: location,
+                            location,
                         },
                     }, {
                         onChunk: streamingCallback,
@@ -65,13 +65,15 @@ export function vertexAiMultiLocation(options) {
     };
     return genkitPlugin(pluginKey, async (_ai) => {
         // Register nothing initially, rely on lazy resolution via resolver
-    }, async (ai, actionType, target) => {
+    }, 
+    // biome-ignore lint/suspicious/useAwait: given
+    async (ai, actionType, target) => {
         if (actionType != 'model') {
             return;
         }
         // Register the action immediately so the lookup succeeds
         // We must register it directly in the registry since ai.defineModel is async and might be too late
-        (ai.registry).registerActionAsync('model', target, createVirtualizedModelAction(ai, target), { namespace: pluginKey });
+        ai.registry.registerActionAsync('model', target, createVirtualizedModelAction(ai, target), { namespace: pluginKey });
     });
 }
 vertexAiMultiLocation.model = function multiLocationModel(baseModel) {

package/ai/genkit/tests/multi-region.test.d.ts

@@ -1 +1,2 @@
+/** biome-ignore-all lint/suspicious/useAwait: defineModel requires async */
 export {};

package/ai/genkit/tests/multi-region.test.js

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/suspicious/useAwait: defineModel requires async */
 import { genkit, GenkitError, z } from 'genkit';
 import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { CircuitBreakerState } from '../../../circuit-breaker/index.js';
@@ -13,6 +14,7 @@ vi.mock('#/utils/array/index.js', async (importOriginal) => {
     };
 });
 vi.mock('@genkit-ai/google-genai', () => ({
+    // biome-ignore lint/style/useNamingConvention: given
     vertexAI: {
         model: vi.fn((name) => ({
             name: `vertexai/${name}`,
@@ -20,6 +22,7 @@ vi.mock('@genkit-ai/google-genai', () => ({
             configSchema: z.object({}),
         })),
     },
+    // biome-ignore lint/style/useNamingConvention: given
     googleAI: vi.fn(),
 }));
 describe('Genkit vertexai-multi-location Plugin Tests', () => {
@@ -39,11 +42,11 @@ describe('Genkit vertexai-multi-location Plugin Tests', () => {
                     locations: ['region-1', 'region-2'],
                     circuitBreakerProvider: cbProvider,
                     logger,
-                    circuitBreakerConfig: { resetTimeout: 1000000, threshold: 1 },
+                    circuitBreakerConfig: { resetTimeout: 1_000_000, threshold: 1 },
                 }),
             ],
         });
-        const config = { threshold: 1, resetTimeout: 1000000 };
+        const config = { threshold: 1, resetTimeout: 1_000_000 };
         await cbProvider.provide('genkit:vertex-ai:location:region-1', config).recordSuccess();
         await cbProvider.provide('genkit:vertex-ai:location:region-2', config).recordSuccess();
         await cbProvider.provide('genkit:vertex-ai:location:cb-fail', config).recordSuccess();

package/ai/parser/parser.js

@@ -5,7 +5,7 @@ import { isDate, isUndefined } from '../../utils/type-guards.js';
  */
 export function parseAiNullableText(text) {
     const trimmed = text?.trim();
-    if (isUndefined(trimmed) || (trimmed == 'null')) {
+    if (isUndefined(trimmed) || (trimmed === 'null')) {
         return null;
     }
     return trimmed;
@@ -16,10 +16,10 @@ export function parseAiDateToNumericDate(dateOrString, allowNull = true, fallbac
     }
     const date = new Date(dateOrString);
     if (Number.isNaN(date.getTime())) {
-        console.warn(`Invalid date string from AI: ${dateOrString}`);
         if (allowNull) {
             return null;
         }
+        // biome-ignore lint/complexity/noArguments: fallback can be passed as undefined
         if (arguments.length >= 3) {
             return fallback;
         }

package/ai/prompts/build.js

@@ -8,6 +8,7 @@ export function buildPrompts(data) {
     const systemInstructions = (isDefined(data.additionalSystemInstructions) && (isString(data.additionalSystemInstructions) || (objectKeys(data.additionalSystemInstructions).length > 0)))
         ? [data.baseSystemInstructions, { 'Additional Instructions': data.additionalSystemInstructions }]
         : data.baseSystemInstructions;
+    // biome-ignore lint/style/useNamingConvention: prompt
     const dataInstructions = isDefined(data.data) ? { Data: `\`\`\`toon\n${formatData(data.data)}\n\`\`\`` } : undefined;
     const outputLanguageInstructions = isDefined(data.language) ? { 'Output Language': languagePrompt(data.language) } : undefined;
     const userInstructions = sections(((isDefined(data.additionalUserInstructions) && (isString(data.additionalUserInstructions) || (objectKeys(data.additionalUserInstructions).length > 0)))

package/ai/prompts/instructions-formatter.d.ts

@@ -70,6 +70,19 @@ export declare function unorderedList(items: InstructionsListContent): Instructi
  * @param items - The list items or map.
  */
 export declare function unorderedList(instruction: string, items: InstructionsListContent): InstructionsList;
-export declare const formatInstructions: (node: Instructions | InstructionsList, options?: {
+/**
+ * Formats a structured instructions object into a string representation suitable for AI prompts (Markdown).
+ *
+ * It recursively handles:
+ * - `sections`: Creates headers (H1, H2...).
+ * - `ordered` / `unordered`: Creates indented lists.
+ * - `Instructions`: Objects are formatted as key-value pairs (e.g., `- **Key:** Value`).
+ *
+ * @param node - The root instructions object, array, or instructions list wrapper.
+ * @param options - Formatting options.
+ * @param options.initialDepth - The starting indentation level (default: 0).
+ * @returns A formatted string.
+ */
+export declare function formatInstructions(node: Instructions | InstructionsList, options?: {
     initialDepth?: number;
-}) => string;
+}): string;

package/ai/prompts/instructions-formatter.js

@@ -1,6 +1,7 @@
 import { memoize } from '../../utils/function/memoize.js';
 import { hasOwnProperty, objectEntries } from '../../utils/object/object.js';
 import { assertDefined, isArray, isDefined, isObject, isString } from '../../utils/type-guards.js';
+const whitespacePattern = /^\s*/;
 // --- Factories ---
 function list(style, instructionOrItems, itemsOrNothing) {
     const instruction = isString(instructionOrItems) ? instructionOrItems : undefined;
@@ -30,7 +31,7 @@ function getPrefix(style, index, sectionDepth) {
         case 'unordered':
             return '- ';
         case 'sections':
-            return '#'.repeat(Math.max(1, sectionDepth)) + ' ';
+            return `${'#'.repeat(Math.max(1, sectionDepth))} `;
         default:
             return '';
     }
@@ -41,24 +42,24 @@ function dedent(text) {
         return text.trim();
     }
     // Remove leading empty line if any (common in template literals)
-    if (lines[0].trim().length == 0) {
+    if (lines[0].trim().length === 0) {
         lines.shift();
     }
     // Remove trailing empty line if any
-    if (lines.length > 0 && lines[lines.length - 1].trim().length == 0) {
+    if (lines.length > 0 && lines.at(-1).trim().length === 0) {
         lines.pop();
     }
-    if (lines.length == 0) {
+    if (lines.length === 0) {
         return '';
     }
     // Find minimum indentation (excluding empty lines)
     const minIndent = lines
         .filter((line) => line.trim().length > 0)
         .reduce((min, line) => {
-        const match = /^\s*/.exec(line);
+        const match = whitespacePattern.exec(line);
         return Math.min(min, match ? match[0].length : 0);
-    }, Infinity);
-    if (minIndent == Infinity) {
+    }, Number.POSITIVE_INFINITY);
+    if (minIndent == Number.POSITIVE_INFINITY) {
         return lines.join('\n').trim();
     }
     return lines.map((line) => line.slice(minIndent)).join('\n').trim();
@@ -162,14 +163,12 @@ function processNode(node, context) {
                 // Section: Header \n\n Content
                 return `${headerLine}\n\n${dedent(effectiveValue)}`;
             }
-            else {
-                // List: "- **Key:** Value"
-                // We need to construct the full string to calculate hanging indent correctly.
-                // headerLine already contains indentation + prefix + key.
-                // We strip the indentation to feed it into the formatting helper effectively.
-                const fullLine = `${headerLine} ${dedent(effectiveValue)}`.trim();
-                return formatWithHangingIndent(fullLine, currentBaseIndent, '');
-            }
+            // List: "- **Key:** Value"
+            // We need to construct the full string to calculate hanging indent correctly.
+            // headerLine already contains indentation + prefix + key.
+            // We strip the indentation to feed it into the formatting helper effectively.
+            const fullLine = `${headerLine} ${dedent(effectiveValue)}`.trim();
+            return formatWithHangingIndent(fullLine, currentBaseIndent, '');
         }
         // If Value is Object/Array/Wrapper
         const body = processNode(effectiveValue, {
@@ -183,21 +182,7 @@ function processNode(node, context) {
         return `${headerLine}${bodySeparator}${body}`;
     }).join(separator);
 }
-export const formatInstructions = memoize(
-/**
- * Formats a structured instructions object into a string representation suitable for AI prompts (Markdown).
- *
- * It recursively handles:
- * - `sections`: Creates headers (H1, H2...).
- * - `ordered` / `unordered`: Creates indented lists.
- * - `Instructions`: Objects are formatted as key-value pairs (e.g., `- **Key:** Value`).
- *
- * @param node - The root instructions object, array, or instructions list wrapper.
- * @param options - Formatting options.
- * @param options.initialDepth - The starting indentation level (default: 0).
- * @returns A formatted string.
- */
-function formatInstructions(node, options = {}) {
+function _formatInstructions(node, options = {}) {
     // Heuristic: If passing a raw object, assume it's a Root Section unless specified otherwise.
     // If passing a Wrapper, the Wrapper dictates the style.
     const initialStyle = isInstructionsList(node)
@@ -212,4 +197,24 @@ function formatInstructions(node, options = {}) {
         sectionDepth: 1,
         style: initialStyle,
     }).trim();
-});
+}
+const formatInstructionsMemoized = memoize(_formatInstructions, { weak: true });
+/**
+ * Formats a structured instructions object into a string representation suitable for AI prompts (Markdown).
+ *
+ * It recursively handles:
+ * - `sections`: Creates headers (H1, H2...).
+ * - `ordered` / `unordered`: Creates indented lists.
+ * - `Instructions`: Objects are formatted as key-value pairs (e.g., `- **Key:** Value`).
+ *
+ * @param node - The root instructions object, array, or instructions list wrapper.
+ * @param options - Formatting options.
+ * @param options.initialDepth - The starting indentation level (default: 0).
+ * @returns A formatted string.
+ */
+export function formatInstructions(node, options = {}) {
+    if (isString(node)) {
+        return _formatInstructions(node, options);
+    }
+    return formatInstructionsMemoized(node, options);
+}

package/ai/prompts/prompt-builder.js

@@ -1,9 +1,11 @@
 import { encodeBase64 } from '../../utils/base64.js';
 import { fromEntries, objectEntries, objectKeys } from '../../utils/object/index.js';
-import { assertObjectPass, isDefined, isString } from '../../utils/type-guards.js';
+import { assertObjectPass, isDefined, isString, isUndefined } from '../../utils/type-guards.js';
 import { formatData } from './format.js';
 import { formatInstructions, sections } from './instructions-formatter.js';
 export class PromptBuilder {
+    #systemMedia = [];
+    #media = [];
     #systemRole;
     #role;
     #systemTask;
@@ -12,8 +14,6 @@ export class PromptBuilder {
     #instructions = {};
     #systemContextParts = {};
     #contextParts = {};
-    #systemMedia = [];
-    #media = [];
     setSystemRole(role) {
         this.#systemRole = role;
         return this;
@@ -47,7 +47,7 @@ export class PromptBuilder {
         return this;
     }
     addSystemContext(titleOrContext, contextOrNothing) {
-        if ((arguments.length == 1)) {
+        if (isUndefined(contextOrNothing)) {
             this.#systemContextParts = { ...this.#systemContextParts, ...assertObjectPass(titleOrContext) };
             return this;
         }
@@ -55,7 +55,7 @@ export class PromptBuilder {
         return this;
     }
     addContext(titleOrContext, contextOrNothing) {
-        if ((arguments.length == 1)) {
+        if (isUndefined(contextOrNothing)) {
             this.#contextParts = { ...this.#contextParts, ...assertObjectPass(titleOrContext) };
             return this;
         }

package/ai/prompts/steering.d.ts

@@ -1,7 +1,8 @@
+import type { ObjectLiteral } from '../../types/types.js';
 import { type Instructions } from './instructions-formatter.js';
 export type FewShotExample = {
-    input: any;
-    output: any;
+    input: ObjectLiteral | null;
+    output: ObjectLiteral | null;
     /** Whether this is a negative example (showing what NOT to do). */
     isNegative?: boolean;
     /** Optional reason explaining why this example is positive or negative. */

package/ai/prompts/steering.js

@@ -13,9 +13,10 @@ function formatExampleValue(value) {
  * @returns A formatted few-shot prompt.
  */
 export function fewShotPrompt(examples) {
-    if (examples.length == 0) {
+    if (examples.length === 0) {
         return {};
     }
+    // biome-ignore-start lint/style/useNamingConvention: prompt
     const entries = examples
         .map((example, index) => {
         const type = example.isNegative ? 'NEGATIVE' : 'POSITIVE';
@@ -31,6 +32,7 @@ export function fewShotPrompt(examples) {
     return {
         Examples: orderedList('Use the following examples to understand the expected input and output format', fromEntries(entries)),
     };
+    // biome-ignore-end lint/style/useNamingConvention: prompt
 }
 /**
  * Creates a prompt addition to specify the output language.

package/ai/tests/instructions-formatter.test.js

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/style/useNamingConvention: instructions are uppercase */
 import { describe, expect, test } from 'vitest';
 import { formatInstructions, orderedList, sections, unorderedList } from '../prompts/instructions-formatter.js';
 describe('Instructions Formatter', () => {