Documentation

@zyno-io/ts-server-foundation is a TypeScript server foundation for HTTP APIs, dependency injection, configuration, database access, workers, SRPC, logging, telemetry, and development tooling.

The TSF compiler emits reflected type metadata used by validation, OpenAPI, routing, DI, config, and database schema extraction. Application code should use the TSF APIs documented here.

Core Docs

Document	Description
Feature Overview	Capability map, architecture boundaries, operational model, and links to every detailed feature guide.
Getting Started	Installation, app creation, module options, DI, lifecycle, and environment requirements.
Public API	Package export surface, root imports, OTel bootstrap imports, and app.http boundary.
Dependency Injection	Providers, scopes, request contexts, module exports, and controller/service lifecycle.
Configuration	BaseAppConfig, Env, env-file loading, child-process env preservation, and built-in config keys.
Environment	Env, snapshots, process-env conversion, config loading behavior, and test patterns.
Database	MySQL/PostgreSQL database layer, active record, sessions, transactions, raw SQL, locks, and schema tools.
SQL	SQL fragments, bindings, identifiers, joins, rendering, and trusted raw SQL escape hatches.
Migrations	Migration files, schema diffing, migration runner, reset, charset, and CLI options.
HTTP	HTTP router, explicit request parameter annotations, multipart uploads, raw streaming, and responses.
Uploads	Multipart parsing, FileUpload, temporary-file cleanup, cached body reads, and raw request streams.
OpenAPI	Route/schema serialization, explicit query/body rules, ApiResponse<T, Status>, and generation commands.
Authentication	JWTs, request helpers, auth middleware, basic auth, password hashing, and reset tokens.
Health Checks	/healthz, HealthcheckService, custom checks, and request logging.
Logging	Pino logging, pretty output, context data, request logs, and error reporting.
Types	Runtime and schema type annotations, including DB/OpenAPI effects for custom types.
Type Reflection	Public runtime reflection, annotation readers, custom validators/deserializers, and shared aliases.
Type Reflection Architecture	Compiler metadata policy shared by validation, OpenAPI, and database extraction.

Services

Document	Description
Workers	BullMQ-backed workers, in-process execution, cron scheduling, recording, and DI-owned job handlers.
Redis	Redis options, cache, mutex, broadcast channels, distributed methods, and BullMQ prefixes.
DevConsole	Development dashboard for routes, OpenAPI, requests, SRPC, DB queries, mutexes, and workers.
SRPC	WebSocket RPC with generated proto types, authentication hooks, bidirectional calls, and byte streams.
Leader Service	Redis-backed leader election.
Mail	DI-registered SMTP/Postmark mail service and templates.
Mesh Service	Redis-backed cross-node typed messaging and broadcasts.
Mesh Client Tracking	Cross-node client registry, invocation, and SRPC mesh integration.

Utilities And Operations

Document	Description
Helpers	Async context, promises, objects, JSON, streams, crypto, validation, dates, errors, UUIDs, and Redis helpers.
Telemetry	OpenTelemetry bootstrap, span helpers, metrics endpoint, shutdown, and Sentry helpers.
Testing	Testing facade, mock HTTP requests, isolated test databases, seed hooks, and assertion helpers.
CLI Tools	tsf, tsf-dev, application REPLs, tests, migrations, protobuf generation, and app scaffolding.
Release	Build, test, OpenAPI generation, package contents, tarball inspection, and publish checklist.
Documentation Maintenance	How to keep the docs aligned with implementation changes.