API Overview

The TypeScript Project Template provides a clean, well-documented API that demonstrates modern TypeScript patterns and best practices. This section covers all the exported functions, types, and utilities.

Auto-Generated API Documentation

For complete, up-to-date API documentation generated directly from the TypeScript source code, see:

📚 Generated API Documentation - Complete API reference with all functions, types, and examples

The generated documentation is automatically created from TSDoc comments in the source code and includes:

• Function signatures with parameter types
• Return type information
• Usage examples
• Type definitions
• Interface documentation

Main Entry Point

main()

The primary application function that demonstrates validation, logging, and configuration management.

export async function main(): Promise<void>

Description: Main application function that showcases the template's validation and logging capabilities.

Returns: Promise<void> - Resolves when the application completes

Example:

import { main } from './index.js';

// Run the main application
await main();

Features Demonstrated:

• Input validation with Zod schemas
• Structured logging with Winston
• Configuration management
• Error handling patterns
• Professional logging practices

Validation Functions

validateUserInput()

Validates user input data using Zod schema with detailed error reporting.

export function validateUserInput(data: unknown): ValidationResult<UserInput>

Parameters:

• data (unknown): Raw user input data to validate

Returns: ValidationResult<UserInput> - Success with typed data or error with details

Example:

import { validateUserInput } from './validation.js';

const result = validateUserInput({
  name: 'John Doe',
  email: 'john@example.com',
  age: 30
});

if (result.success) {
  // TypeScript knows result.data is UserInput
  console.log(`Welcome, ${result.data.name}!`);
} else {
  console.error('Validation failed:', result.error);
}

validateAppConfig()

Validates application configuration with comprehensive schema checking.

export function validateAppConfig(data: unknown): ValidationResult<AppConfig>

Parameters:

• data (unknown): Raw configuration data to validate

Returns: ValidationResult<AppConfig> - Success with typed config or error details

Example:

import { validateAppConfig } from './validation.js';

const configData = JSON.parse(fs.readFileSync('config.json', 'utf-8'));
const result = validateAppConfig(configData);

if (result.success) {
  const config = result.data;
  console.log(`Starting ${config.app.name} v${config.app.version}`);
}

ValidationError

Custom error class for validation failures with structured error information.

export class ValidationError extends Error {
  public readonly issues: z.ZodIssue[];

  constructor(message: string, issues: z.ZodIssue[]);
  public getFormattedMessage(): string;
}

Properties:

• issues - Array of validation issues from Zod
• name - Always 'ValidationError'

Methods:

• getFormattedMessage() - Returns formatted error with field details

Logging Functions

createLogger()

Creates a configured Winston logger instance with specified options.

export function createLogger(config: LoggerConfig): winston.Logger

Parameters:

• config (LoggerConfig): Logger configuration options

Returns: winston.Logger - Configured Winston logger instance

Example:

import { createLogger } from './logger.js';

const logger = createLogger({
  level: 'info',
  outputFile: 'app.log',
  includeTimestamp: true,
  useColors: false
});

logger.info('Application started', { port: 3000 });

createLoggerFromConfig()

Creates a logger from application configuration.

export function createLoggerFromConfig(config: LoggingConfig): winston.Logger

Parameters:

• config (LoggingConfig): Logging section from app configuration

Returns: winston.Logger - Configured logger instance

Logger Utilities

The loggerUtils object provides common logging patterns:

export const loggerUtils: {
  logValidationSuccess(logger: ILogger, message: string, data?: object): void;
  logValidationFailure(logger: ILogger, message: string, error: string): void;
  logSectionHeader(logger: ILogger, title: string): void;
  logStartup(logger: ILogger, appName: string, version?: string): void;
  logCompletion(logger: ILogger, message: string): void;
}

Example:

import { logger, loggerUtils } from './logger.js';

loggerUtils.logStartup(logger, 'MyApp', '1.0.0');
loggerUtils.logValidationSuccess(logger, 'Input validated', userData);
loggerUtils.logSectionHeader(logger, 'Processing Phase');
loggerUtils.logCompletion(logger, 'Process completed successfully');

Configuration Management

ConfigManager

Type-safe configuration loading and validation class.

export class ConfigManager {
  constructor(configPath?: string);

  loadConfig(): ValidationResult<AppConfig>;
  getConfig(): AppConfig | null;
  getServerConfig(): ServerConfig;
  getLoggingConfig(): LoggingConfig;
  getAppConfig(): AppConfigSection;
  isFeatureEnabled(featureName: string): boolean;

  static validateConfigFile(configPath?: string): ValidationResult<AppConfig>;
}

Example:

import { ConfigManager } from './config.js';

const configManager = new ConfigManager();
const result = configManager.loadConfig();

if (result.success) {
  const serverConfig = configManager.getServerConfig();
  const logger = createLoggerFromConfig(configManager.getLoggingConfig());

  if (configManager.isFeatureEnabled('enableMetrics')) {
    setupMetrics();
  }
}

Utility Functions

delay()

Delays execution for a specified number of milliseconds.

export async function delay(ms: number): Promise<void>

Parameters:

• ms (number): Number of milliseconds to delay

Returns: Promise<void> - Resolves after the delay

Example:

import { delay } from './utils.js';

// Wait for 1 second
await delay(1000);

// Use in async functions
async function processWithDelay() {
  console.log('Starting...');
  await delay(500);
  console.log('Continuing after delay...');
}

safeJsonParse()

Safely parses JSON with comprehensive error handling.

export function safeJsonParse(jsonString: string): AsyncResult<unknown>

Parameters:

• jsonString (string): JSON string to parse

Returns: AsyncResult<unknown> - Success or error result

Example:

import { safeJsonParse } from './utils.js';

// Parse valid JSON
const result1 = safeJsonParse('{"key": "value"}');
if (result1.success) {
  console.log(result1.data); // { key: "value" }
}

// Handle invalid JSON
const result2 = safeJsonParse('invalid json');
if (!result2.success) {
  console.error(result2.error); // "Unexpected token i in JSON at position 0"
}

formatTimestamp()

Formats a Unix timestamp into a human-readable string.

export function formatTimestamp(
  timestamp: number, 
  config: UtilConfig = {}
): string

Parameters:

• timestamp (number): Unix timestamp in milliseconds
• config (UtilConfig, optional): Configuration options

Returns: string - Formatted date string in "YYYY-MM-DD HH:mm:ss" format

Example:

import { formatTimestamp } from './utils.js';

// Basic usage
const formatted = formatTimestamp(Date.now());
console.log(formatted); // "2024-01-15 14:30:00"

// With debug logging
const debugFormatted = formatTimestamp(Date.now(), { debug: true });
// Logs: "Formatted timestamp 1705327800000 to 2024-01-15 14:30:00"

Type Definitions

UtilConfig

Configuration interface for utility functions.

export interface UtilConfig {
  /** Enable debug logging */
  debug?: boolean;
  /** Maximum retry attempts */
  maxRetries?: number;
  /** Timeout in milliseconds */
  timeout?: number;
}

Properties:

• debug (boolean, optional): Enable debug logging for operations
• maxRetries (number, optional): Maximum number of retry attempts
• timeout (number, optional): Timeout in milliseconds for operations

AsyncResult<T>

Result type for operations that can succeed or fail.

export type AsyncResult<T> = {
  success: true;
  data: T;
} | {
  success: false;
  error: string;
};

Type Parameters:

• T: The type of data returned on success

Usage Pattern:

function processResult<T>(result: AsyncResult<T>): void {
  if (result.success) {
    // TypeScript knows result.data is type T
    console.log('Success:', result.data);
  } else {
    // TypeScript knows result.error is string
    console.error('Error:', result.error);
  }
}

Error Handling Patterns

The API demonstrates several error handling approaches:

1. Validation Result Pattern

// Validation functions return Result types
const result = validateUserInput(userData);
if (result.success) {
  // TypeScript knows result.data is UserInput
  const user = result.data;
  logger.info('User validated', { userId: user.name });
} else {
  // TypeScript knows result.error is string
  logger.error('Validation failed', { error: result.error });
}

2. ValidationError with Details

// Custom ValidationError for detailed error information
try {
  const data = UserInputSchema.parse(input);
} catch (error) {
  if (error instanceof ValidationError) {
    logger.error('Validation failed', {
      message: error.getFormattedMessage(),
      issues: error.issues.map(issue => ({
        field: issue.path.join('.'),
        message: issue.message
      }))
    });
  }
}

3. Promise-Based Errors

// Functions that can reject
async function riskyOperation(): Promise<string> {
  if (Math.random() > 0.5) {
    throw new Error('Random failure');
  }
  return 'Success';
}

// Proper error handling with logging
try {
  const result = await riskyOperation();
  logger.info('Operation succeeded', { result });
} catch (error) {
  logger.error('Operation failed', {
    error: { message: error.message, stack: error.stack }
  });
}

4. Result-Based Errors

// Functions that return success/error objects
const result = safeJsonParse(jsonString);
if (result.success) {
  // Handle success case
  processData(result.data);
} else {
  // Handle error case with structured logging
  logger.error('JSON parse failed', { error: result.error, input: jsonString });
}

Best Practices Demonstrated

1. Type Safety

• All functions have explicit return types
• Zod schemas provide runtime type validation
• Interfaces define clear contracts
• Union types for result handling

2. Input Validation

• Validate all external data with Zod schemas
• Use Result types for consistent error handling
• Provide detailed validation error messages
• Type inference from validation schemas

3. Professional Logging

• Structured logging with metadata
• Appropriate log levels for different scenarios
• Environment-aware configuration
• Logger utility functions for common patterns

4. Configuration Management

• Type-safe configuration loading
• Validation of configuration files
• Feature flags for conditional functionality
• Environment-specific configurations

5. Documentation

• TSDoc comments for all exported functions
• Parameter descriptions and examples
• Return type documentation
• Usage examples with error handling

6. Error Handling

• Multiple error handling patterns
• Graceful degradation
• Informative error messages
• Structured error reporting

7. Async Patterns

• Proper Promise usage
• Async/await best practices
• Timeout handling
• Error propagation

8. Testing Support

• Functions designed for easy testing
• Predictable behavior
• Mockable dependencies
• Comprehensive test coverage

Usage Examples

Complete Application Example

import { main, delay, safeJsonParse, formatTimestamp } from './index.js';
import { logger, loggerUtils } from './logger.js';
import { validateAppConfig } from './validation.js';
import { ConfigManager } from './config.js';

async function myApplication() {
  loggerUtils.logStartup(logger, 'MyApplication', '1.0.0');

  // Load and validate configuration
  const configManager = new ConfigManager();
  const configResult = configManager.loadConfig();

  if (!configResult.success) {
    logger.error('Configuration validation failed', { error: configResult.error });
    return;
  }

  loggerUtils.logValidationSuccess(logger, 'Configuration loaded', {
    environment: configResult.data.app.environment
  });

  // Parse additional configuration
  const extraConfigResult = safeJsonParse('{"timeout": 5000}');
  if (!extraConfigResult.success) {
    logger.error('Invalid extra configuration', { error: extraConfigResult.error });
    return;
  }

  // Wait before processing
  logger.info('Starting processing delay', { duration: '1000ms' });
  await delay(1000);

  // Run the main application logic
  loggerUtils.logSectionHeader(logger, 'Main Application Logic');
  await main();

  loggerUtils.logCompletion(logger, 'Application completed successfully');
}

// Run with comprehensive error handling
myApplication().catch(error => {
  logger.error('Application failed', {
    error: {
      message: error.message,
      stack: error.stack
    }
  });
  process.exit(1);
});

Next Steps

• Main Functions - Detailed documentation of main entry points
• Utilities - Deep dive into utility functions
• Types - Complete type definitions and interfaces
• Validation System - Comprehensive validation documentation
• Logging System - Professional logging guide
• Configuration Management - Type-safe configuration