@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

npm install @tstdl/base

🚀 Quick Start

Most applications start by bootstrapping the Dependency Injection container and the Application lifecycle manager.

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.

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.