ts-bakery/CLAUDE.md

Baked dependency injection for Typescript.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ts-bakery is a TypeScript dependency injection library that uses decorators and a configuration-based approach. The project provides "baked" dependency injection through compile-time analysis and runtime resolution.

## Development Commands

- `npm run build` - Clean build directory and compile TypeScript to build/
- `npm run watch` - Clean build and compile with watch mode
- `npm test` - Run Mocha tests with ts-node (uses commonjs module compilation)

## Architecture

### Core Components

**Dependency Resolution System**
- `DependencyResolver` (abstract): Core resolver that manages module registration, dependency instantiation, and lifecycle
- `DependencyResolverModule` (abstract): Base class for dependency modules that register class bindings
- `DependencyRegistrationBuilder`: Fluent API for configuring dependency registrations

**Configuration System**
- `DependencyConfiguration`: Container for bindings and mappings between interfaces and implementations
- `DependencyConfigurationProvider`: Loads dependency configuration from file system analysis
- `DependencyBinding`: Maps abstract dependencies to concrete implementations
- `DependencyMapping`: Defines constructor parameter dependencies for a given class

**Decorator System**
- `@inject`: Marks methods for dependency injection (method injection)
- `@postInject`: Marks methods to run after dependency injection
- `@postResolve`: Marks methods to run after all dependencies are resolved
- `DecoratorRegistry`: Tracks decorated methods for runtime invocation

### Key Design Patterns

1. **Module-based Registration**: Dependencies are organized into modules that extend `DependencyResolverModule`
2. **Configuration-driven**: Uses filesystem analysis to generate dependency mappings and bindings
3. **Lifecycle Management**: Supports singleton/transient instances with post-injection and post-resolution hooks
4. **Method Injection**: Supports both constructor injection and method-based injection via `@inject`
5. **Access Restrictions**: Dependencies can restrict which classes can request them

### Project Structure

- `source/Configuration/` - Dependency binding and mapping configuration
- `source/Injection/` - Core DI container, decorators, and registration builders
- `source/Types/` - TypeScript AST representation classes
- `source/Conversion/` - TypeScript parsing and analysis utilities
- `source/NodeSequencing/` - Pattern matching for TypeScript AST nodes
- `source/Util/` - Utility classes for CLI and path management
- `test/` - Test classes and dependency injection test modules

### TypeScript Configuration

- Target: ES6 with CommonJS modules
- Decorators enabled (`experimentalDecorators`, `emitDecoratorMetadata`)
- Source maps and declarations generated
- Base URL set to `source/` for clean imports

## Testing

Tests are located in `test/Tests/` and use Mocha with ts-node. Test dependencies are organized in `test/Classes/InjectionTests/` with separate modules (ModuleA, ModuleB, ModuleC) to verify cross-module dependency resolution.